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Production Note 


This book was produced with the VAX DOCUMENT electronic publishing 
system, a software tool developed and sold by Digital. In this system, 
writers use an ASCII text editor to create source files containing text and 
English-like code; this code labels the structural elements of the document, 
such as chapters, paragraphs, and tables. The VAX DOCUMENT software, 
which runs on the VMS operating system, interprets the code to format 
the text, generate a table of contents and index, and paginate the entire 
document. Writers can print the document on the terminal or line printer, 
or they can use Digital-supported devices, such as the LN0O3 laser printer 
and PostScript printers (PrintServer 40 or LNO3R ScriptPrinter), to 
produce a typeset-quality copy containing integrated graphics. 
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Preface 


The Guide to Producing Online Documentation collects information 
required by all CUP personnel involved in producing online 
documentation. 


A broad description of the relation of writers, editors, Graphic Services 
personnel, and online project leaders in the online production process 
appears in Chapter 1. Specific information for each of these individual 
groups appears in subsequent chapters. 


Writers maintaining hardcopy books may consult Chapter 2 for assistance 
in adapting an existing set of SDML source files so that they produce 

an online book when processed for one of VAX DOCUMENT’s online 
doctypes and in enhancing a book’s appearance when it is displayed by the 
DECwindows Bookreader. 


Writers of new manuals should refer to Chapter 2 for online writing 
guidelines. 


Editors should turn to Chapter 3 for information about their 
responsibilities in the hardcopy/online and online-only production 
processes. Chapter 4 discusses the hardcopy/online and online-only 
production processes and the work performed by Graphic Services in 
producing online documentation. 


The duties of the online project leader are discussed in Chapter 5. 


Associated Documents 


The primary resource for DOCUMENT online coding is Coding 
Documentation Source Files for the DECwindows Bookreader. CUP 
Engineering frequently updates this document to reflect the latest 
baselevel of the online software. Obtain a copy from: 


CLOSET: :KITS_: [DOCUMENT.V12]WRITER_GUIDELINES.PS 


You can obtain complete information about the Screen Capture and Image 
Manipulation Program (UTOX) from the UTOX User’s Guide. Obtain a 
copy from: 


AIRBAG: : SYS$PUBLIC: [UTOX]UTOX_USERS_GUIDE.PS 
You can also obtain a UTOX beginner’s guide from: 
NEWDOC : : SYSSINFO:UTOX_GET_STARTED.PS 


For a complete discussion of the Raster Graphics Editor System (RAGS), 
pee the Guide to VAX RAGS. You can obtain either an LNO3 or PostScript 
copy from the following location: - | 


CLOSET: :W4_: (PUBLIC. RAGS .V051)] RAGS .LNO3 
CLOSET: :W4_: [PUBLIC.RAGS .V051] RAGS .POST 


1.1 


Introduction 


The skills of writers, editors, artists, proofreaders, and project leaders are 
all required in the effort to produce high-quality online documentation. 
The online documentation effort requires that each individual understand 
and follow a set of defined procedures for fulfilling his or her role and that 
all individuals cooperate in exchanging information and files in an orderly 
and defined manner. 


Overview 


The online documentation effort involves the following three phases: 
¢ Pre-production 

¢ Production 

e Manufacturing 


Writers, editors, and proofreaders perform pre-production work; writers 
are less involved in the production phase. The manufacturing phase 
involves the online documentation release engineer, the Software Quality 
Maintenance (SQM) group, the Software Supply Business (SSB) group 
(formerly the SDC), and Graphic Services. An online project leader in the 
writing group monitors the work performed in all three phases) 


The production phase for online documentation can involve either of two 
defined production processes: 


¢ Online-only—The manual produced in online format only or its being 
prepared for its initial online release. The writer must adapt the book's 
source files so that they successfully build for a VAX DOCUMENT 
online doctype. A previously-converted online manual with revisions 
(and no associated hardcopy edition) also goes through the online-only 
production cycle. 


¢ Online/hardcopy —The manual will be available in online and 
hardcopy forms at the same time. 


This manual describes the procedures writers, editors, Graphic Services 
personnel, online project leaders, and compact disc (CD) release engineers 
follow to support an online-only or online/hardcopy release. 


1 The tasks assigned to the online project leader role may in reality be performed by editors, writers, and 
documentation management. 
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1.2 Producing Online Documentation 


1.2 Producing Online Documentation 


Documentation managers, supervisors, and project leaders are responsible 
for the following tasks: 


¢ Deciding which books are published online-only or hardcopy-only 


© Deciding which books are published simultaneously online and 
hardcopy (online/hardcopy) 


¢ Developing writing, conversion, and production schedules 

e Ensuring that schedules are met 

¢ Monitoring the quality of online books 

Writers, editors, artists, operators, proofreaders and CD release engineers 


are responsible for writing, editing, and producing online books according 
to schedules defined by management. 


The following tables illustrate the flow of the online production processes 
and indicate who is responsible for a given task. The accompanying tables 
further explain these responsibilities. 


Table 1—1 illustrates the online-only production cycle. 
Table 1-2 illustrates the online/hardcopy production cycle. 


The abbreviations used in the tables indicate the individuals responsible 
for online book publication tasks, as follows: 


Abbreviation Meaning 

M Writing manager 

Ww Writer 

E Editor 

GS Graphic Services 

PL Project leader’ 

DB Document set builder (VMS writing group only) 
RE Release engineer 

SQM Software Quality Maintenance group 
SSB Software Supply Business group 

Vv Vendor 


TE Se rene re ree aaa nl 
‘The tasks assigned to the online project leader role may in reality be performed by editors, 
writers, and documentation management. 


For additional information about any task mentioned in the tables, refer 
to the appropriate chapter in this manual. 
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Table 1-1 Online-Only Tasks and Responsibilities 


Task Process 
Preproduction Tasks 

Writing book Writer 

Editing book Editor 
Converting files to online’ Writer 
Coordinating art conversion' Editor 
Converting art to online’ Artist 

Checking converted art' Proofreader 
Performing online bookbuild Writer or document set builder 
Checking book online Writer and editor 
Submitting online submission form Project leader 


Creating preliminary product definition form 


Final Production Tasks 


Release engineer 


Putting files into CMS Writer 

Checking book online Editor and proofreader 
Buliding book for final production Writer or document set builder 
Checking final bookbuilds Writer, editor, and proofreader 
Making final corrections Writer or GS operator 
Performing final bookbuild Writer, document set builder, or GS operator 
Submitting online books to release engineer Project leader 

Manufacturing Tasks 

Applying and testing licenses Release engineer 

Submitting files to SQM Release engineer 
Premastering files SQM 

Sending files to SSB SQM 


'Theee tasks only required only for hardcopy books never previously published online. 
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cd 


Table 1-2 Online/Hardcopy Tasks and Responsibilities 
‘ask Responsible Individual 


~{ 


Preproduction Tasks 


Writing book Writer 

Editing book Editor 

Obtaining LPN Editor 
Requesting CMS library Editor 

Opening CMS Library CMS librarian 
Converting files to online’ Writer 
Coordinating art conversion’ Editor 
Converting art to online’ Artist 

Checking converted art' Proofreader 
Coordinating art package Editor 

Preparing art package Artist 

Inserting pica measurements in figure file Writer 

tags 

Performing hardcopy and online bookbuilds § Writer 

Checking book online Writer and editor 
Submitting printspec info for hardcopy Editor 
Submitting online submission form Project leader 
Creating preliminary PDF Release engineer 


Final Production Tasks 


Building book for final production Writer 

Putting files into CMS Writer 

Submitting book to GS Editor 

Generating PostScript and VT600 copies GS operator 

Checking PostScript and VT600 copies Editor and proofreader 

Performing final bookbulids GS operator 

Checking book ontine Editor, proofreader, and GS operator 
Making final corrections GS operator 

Preparing repro package Editor 


Submitting online books to release engineer Project leader 


(continued on next page) 
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1.2 Producing Online Documentation 


Table 1-2 (Cont.) Online/Hardcopy Tasks and Responsibilities 


Task Responsibie Individual 
Manufacturing Tasks 

Applying and testing licenses Release engineer 
Submitting files to SQM Release engineer 
Premastering files SQM 

Sending files to SSB SQM 
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2 Online Writing Guidelines 


This chapter provides updated procedures for writing manuals that will be 
published online. It includes the following information: 


¢ References to additional documents 

¢ Details to include in your docplan 

e An explanation of the pre-production meeting 

¢ Instructions for creating or converting art 

© Writing guidelines | 

e An overview of the cleanup procedures for converting a hardcopy book 
to online format 


¢ Tips on DOCUMENT coding conventions and tools for facilitating 
online builds ~ 
¢ Procedures for building and viewing an online book 


¢ Asummary of the requirements for submitting a book to Graphic 
Services 


2.1 Overview of Writing Procedures 


A primary goal of the VAX DOCUMENT software is to allow you to 
produce a book for any given output device, in any defined format, from 
a single set of SDML source files. To support online documentation in 
a form readable by the DECwindows Bookreader, VAX DOCUMENT 
has introduced the BOOKREADER output destination and the ONLINE 
doctypes. 


The ONLINE doctypes and DECwindows Bookreader software do not 
require the addition of new SDML tags to existing DOCUMENT source 
files. However, they do rely on certain coding conventions. 


If you are converting a hardcopy book to online format, some of the 
conventions required by the ONLINE doctype quite possibly were 

not followed in producing the original hardcopy-oriented source files. 
Additionally, because the online form of output has made hardcopy, pasted- 
in artwork obsolete, any artwork included in a given book must be redrawn 
and the associated SDML code must be revised. Finally, source files must 
provide symbol-names for each piece of a book so that the DECwindows 
Bookreader can find any referenced location easily. 


When you are writing a new manual, you have to be concerned about 
three main areas: writing the manual, coding the manual, and meeting 
certain production requirements. The advent of online documentation has 
changed and added some procedures in each of these areas. 
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2.2 Obtaining Information About Producing Online Documentation 


The most authoritative information about coding DOCUMENT source 
files to be built in online format viewable by the DECwindows Bookreader 
appears in Coding Documentation Source Files for the DECwindows 
Bookreader. This document contains information about the DOCUMENT 
command line, the DOCUMENT tags that are required by the online 
doctypes, and the tags that help make the output file more readable when 
displayed by the DECwindows Bookreader. It also includes information 
about the location and installation of the Bookreader software and tools, 
as well as a list of known problems. 


CUP Engineering continuously revises Coding Documentation Source Files 
for the DECwindows Bookreader to reflect the latest baselevel of the online 
software. Obtain a copy from: 


CLOSET: :KITS_: [DOCUMENT.V12]WRITER_GUIDELINES.PS 


All new online VAX document tags discussed in this chapter are described 
fully in Coding Documentation Source Files for the DECwindows 
Bookreader. 


Individual writing. groups have supplemented these online writing 
guidelines with group-specific guidelines. For instance, the VMS 
Documentation group has required that SDML source files be named 
with the SDML file extension (not .GNC). This is not a requirement of the 
online software. 


You may also find useful information (and food for thought) in the 
CLOSET::ONLINE_BOOKBUILDING notes conference. This is the 
conference in which to report problems with the online bookbuilding tools 
and offer suggestions and criticisms. It is monitored by CUP Engineering 
and the DECwindows Bookreader engineers. 


2.3 Writing Your Docplan 
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When writing a docplan for a manual that is to be produced online, you 
should consider the following points: 


¢ As well as indicating that your manual is a new or revised document, 
the docplan should state whether the manual will be published in 
online-only or in online and hardcopy versions. 


e The docplan should state the online doctype of the manual, either 
ONLINE.REFERENCE or ONLINE.HANDBOOK. 


¢ The milestones listed in the docplan should allow ample time for 
editing (including extra time for index editing during the second pass 
edit) and proofreading support of the online version. 

¢ The docplan should state whether online help that requires editing 
and proofreading will accompany the manual. 

¢ The docplan should state art requirements, such as how many 


unannotated and annotated screen captures and figures will be 
included in the manual. 
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Online Writing Guidelines 
2.4 Attending the Pre-Production Meeting 


Attending the Pre-Production Meeting 


Before you submit a book to Graphic Services (GS) for online proofreading 
or online/hardcopy production, a pre-production meeting should be held to 
define the work required by GS. 


As a writer, you will need to provide the following information at the 
meeting: 
¢ Title and LPN for each book 


¢ Schedule of submittal of each book, including the date of submittal to 
GS and date of submittal to SSB 

¢ Type of production required (online/hardcopy, online-only, hardcopy- 
only) 

¢ Page count estimate 


¢ Estimated number of new and revised art figures, and anticipated 
format (UTOX, RAGS) 


You might also need to provide information on the submittal process (for 
online-only books) and the target Online Documentation (OLD) disc. For 
more information, see Chapter 3. 


Creating Art 


Note: 


Online documentation has changed the manner in which art is created and 
delivered for your book. No longer will your editor deliver to you a copy of 
hand-drawn art. However, an editor will work with you to determine the 
art requirements for your book. (For example, will existing art need to be 
corrected or modified? What new art will Graphic Services need to create? 
Will screen captures be included?) 


This section describes which procedures you should follow to ensure that 
completed art will be included in your online and hardcopy versions. 


As always, you should conceptualize and request your art as early 
as possible in the writing process. You should submit all art six 
weeks before final production. 


Creating Art for Review Drafts 


If you can give your art requirements to Graphic Services early enough, 
the artists can create the new art for your review drafts. However, if 
that is not possible, follow the procedures in this section to create the art 
yourself. This section also explains how to use screen dumps and existing 
art for your review drafts. 
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2.5 Creating Art 


2.5.1.1 Creating New Art 
You can use the <LINE_ART> and <ENDLINE_ART> tags, as always, to produce 
monospaced keyboard-character art in online and hardcopy review drafts. 
You can also generate your own art for review drafts using RAGS. The 
RAGS kit save set is available in: 


CLOSET: :W4_: (PUBLIC.RAGS.V051] RAGSOS1 


You can copy the Guide to VAX RAGS in .LNO3 or .POST formats from the 
same directory: 


CLOSET: :W4_: [PUBLIC.RAGS.V051])RAGS_ USERS GUIDE .XXX 


2.5.1.2 Creating Screen Output 
Use the UTOX utility to capture screens that you want to display in your 
documentation. UTOX produces screen output in the form of SDML 
files in a variety of formats, for example .SDML-BIN for the Bookreader, 
SSDML-PS for PostScript files, and .SDML-SIXEL for sixel files. 


You must generate all screen images (for the final draft as well as for 
review drafts); Graphic Services does not generate screen art. If you are 
including UTOX-generated screens in your manual, be sure to talk to your 
editor early in the draft cycle about design and sizing issues. 


Unannotated Screen Art 


After you generate unannotated screen art, store the SDML-xxx graphics 
files in your directory with the other book elements. You should maintain 
these UTOX graphics just as you maintain your individual chapter files 

‘and other book elements. You should precede the name of the screen file 
with the LPN of your manual, as in the following examples: 


9999CUSTOMIZE.SDML-BIN 
9999CUSTOMIZE .SDML~-PS 
9999CUSTOMIZE . SDML-SIXEL 


Don’t use chapter or part numbers in the file name. 


Annotated Screen Art 


If any UTOX-generated screens need graphic annotation, you should create 
hardcopy and online samples for Graphic Services. Graphic Services will 
annotate the screens using RAGS, apply art control numbers, and place 
them in the ARTOUT directory on DONVAN.! 


From then on, annotated screen art will be considered GS-generated art. 
Graphic Services will perform any modifications to the annotated screen 
art. If the screen image of an annotated screen needs to be changed, you 
should resubmit a hardcopy and online sample of the new screen image to 
Graphic Services. 


The UTOX kit save set is available in: 
AIRBAG: : SYS$PUBLIC: [UTOX] UTOX020 


? For VMS books, the production coordinator will copy the art to the ARTLIB directory on STAR. 
2-4 


2.5.2 


2.5.3 


2.5.1.3 


Coding a Figure 


2.5 Creating Art 


You can copy the UTOX User’s Guide in PostScript format from: 
AIRBAG: : SYS$PUBLIC: [UTOX) UTOX_USERS GUIDE.PS 

You can also obtain a UTOX beginner’s guide from: 

NEWDOC: : SYSSINFO:UTOX_GET_STARTED.PS 


CUP offers a training session on using RAGS and UTOX. Contact Mike 
Etzel on DONVAN::ETZEL for more information on this session. 


Using Existing Art 

If you need any existing art pieces, you should request these from your 
editor. Your editor checks with Graphic Services to determine if these 
art pieces have been converted to RAGS art. If not, your editor submits 
marked-up copies of existing art to Graphic Services. An artist redraws 
the art and places the revised art file in an art directory. 


Creating Art for Final Drafts 


At least six weeks before final production, you should give instructions 
for new art to Graphic Services. If all or part of your art requirements 
are changing at this point, inform your editor and artist that you will be 
requiring art and negotiate a deadline for submitting the requirements. 


The artists generate source files using RAGS. The same source files will be 
used to create the formats that will generate online and hardcopy versions 
of the art. These formats follow: 


¢ DECWS$BOOKFIG for BOOKREADER output 
e SIX for LNO3 output 
¢ PS for Postscript output 


The artist will place the finished art files in the ARTOUT directory on 
DONVAN.! When the art package has been completed, the editor will give 
you a final art control list. 


Refer to Section 2.5.1.2 for information on creating screen output in your 
final drafts. 


For information on coding a figure for online viewing, refer to step 4 of the 
Required tasks of Section 2.8.3. 


Refer to Section 2.10.1 of this manual for procedures you should follow 
after the artists complete the art package. 


1 For VMS books, the production coordinator will copy the art to the ARTLIB directory on STAR. 
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2.6 Writing the Manual 


This section includes guidelines that will help you organize your books so 
that readers will easily find the information they need. You should follow 
these guidelines throughout the writing i aa Trying to implement them 
all at the end is ineffective. 


The guidelines are organized by the ‘lleeing topics: 
e Organizing information 

© Writing introductions 

¢ Using cross-references 

e Using terminology 

¢ Using tables, figures, and examples 

e Writing and reviewing the index 


When writing a manual, refer to the 32V Style Guide for 32V style and 
usage information. 


2.6.1. Organizing Information 
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2.6.1.1 


2.6.1.2 


Organize information in a consistent and logical way. At the highest level, 
an outline, which develops into a table of contents, should demonstrate 

a document's logical structure. At the chapter and section level, the text 
should reveal information in a logical manner. Descriptive text should 
disclose information progressively. Reference material should provide 
information in a consistent format that reflects how the information is to 
be used. Make sure paragraphs and sentences stick to one subject. 


This section recommends several techniques to help you organize your 
information and achieve clarity in your documentation. 


Writing Book Titles 

Now that users will be scanning the bookshelf file to find the book that 
contains the appropriate information for them, it is important that the 
book titles accurately describe the information in them. 


Writing Chapter and Part Titles 

Write chapter and part titles to specifically describe what information the 
chapter or part contains. For example, the following two chapter titles are 
more specific than the generic title Interprocess Communication: 


Interprocess Communication Concepts 
Interprocess Communication on a VMS System 


Make sure every chapter title has text following it. The Bookreader uses 
heads to define Next and Previous Topics; if, for example, you have no text 
following a chapter heading, pressing on Next or Previous Topic will bring 
up the chapter title alone on the screen. Therefore, following the chapter 
heading, give a brief overview of the upcoming chapter before you begin 
with the first HEAD1. 


2.6.1.3 


2.6.1.4 


2.6.1.5 


2.6 Writing the Manual 


Writing Section Headings 

Section headings are especially valuable for the online reader because the 
reader maneuvers through the book by clicking from one head to another. 
Like chapter headings, section headings should give the reader a clear 
idea of what information is in the text that follows them. 


Keep the following points in mind when writing section headings: 
¢ Make sure section headings accurately reflect contents of sections. 


¢ Do not use more than 3 header levels (3.1, 3.1.1, 3.1.1.1). Deeper 
outlines are difficult to follow. 


¢ Use abundant section headings so that text is well-labeled and easier 
to find. 


¢ Where possible, use noun phrases for chapter titles and gerund 
phrases for first level headers. For example: 


3 Installation Procedures 
3.1 Installing the Software 


e Avoid starting section header titles with a, an, or the. 


¢ Repeat all important header title information; do not assume the 
reader has read the head. For example: 


3 Source, Intermediate, and Final Files 
To create source, intermediate, and final files... 
not 


To create these files... 


Creating White Space 
Reading information on line can be visually straining. Give users white 
space! To create white space, use the following techniques: 


e Be concise. After writing a section, review it to see whether you have 
been verbose or redundant. Decide whether you really need each 
paragraph. 

e Avoid long narrative paragraphs. Check to see whether long 
paragraphs can be split into shorter paragraphs. 

© Use lists. They clarify and emphasize the information you are 
presenting. 

© Consider replacing text with art. 


Using Highlighting 

Do not overuse bold, italics, and all caps. These typeface changes are 
more noticeable in an online document. Make your point using text and 
graphics, not highlighting. 


Note: Remember that user input in examples (all text after a <U> tag) is 


bold in online text. 
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2.6.2 Writing introductions 


2.6.2.1 


2.6.2.2 


2.6.2.3 


Well-focused introductions are useful because they enable readers to decide 
whether they can get the information they need in the text that follows 
them. The preface, chapter introductions, and section introductions are 
some of the pathways readers will take té find information in your manual. 


Writing the Preface 

State the book’s purpose clearly in the preface. Users need an easy way 
to make sure they’re looking in the right book. List each chapter and 
briefly describe the topic for each one. Clearly identify the audience of the 
manual and list related documentation. 


Writing Chapter introductions 

Use chapter introductions as springboards for locating material in the 
sections that follow. For each chapter introduction, consider including an 
unnumbered list of the major topics discussed in that chapter. Think of 
chapter introductions as guides that offer pointers more descriptive than 
those in the Table.of Contents but less detailed than those in the index. 


Writing Section Introductions 
Whenever possible, make sure that every first level head section includes 
an introduction to the information you are presenting in that section. 


2.6.3 Using Cross-References 
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The DECwindows Bookreader enables you to create hot spots when you 
cross-reference information in your manual. A hot spot is a cross-reference 
that takes readers directly to the referenced materia] when they click 

on the cross-reference. This enables readers to find cross-referenced 
information easily. The DECwindows Bookreader defines the contents of a 
hot spot from information supplied by the <REFERENCE> tag. 


You can use cross-referencing in the Preface, as well as thoughout the 
manual. Keep the following points in mind when you cross-reference 
information: 


¢ Create hot spots in the chapter titles when you describe each chapter 
in the preface. The user will be able to click on the chapter title and 
go directly to the chapter. 


© When introducing a chapter or section, refer to other books or sections 
within your manual that will give the reader background or additional 
information. 


© Use cross-references throughout the manual where appropriate. 


2.6.4 Using Terminology 
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Keep the following guidelines in mind when you use terminology in your 
manual: 


Use consistent terminology. Do not use synonyms interchangeably. 


Define al] terms at the first occurrence. After you define a term, use 
that term throughout the manual. Redefine if necessary for reader 
understanding. 


At first occurrence, spell out an abbreviation or acronym and follow it 
with the shortened form in parentheses. 


Do not use above and below. Be specific when you point a reader to 
another section for more information on a certain term or topic. If the 
reader clicks on a properly-coded section reference, the Bookreader will 
immediately take the reader to that section. 


2.6.5 Using Tables, Figures, and Examples 


Table, figure, and example placement is important. It makes the online 
display visually attractive and helps the reader quickly find information. 
Consider the following points when using tables, figures, and examples: 


Always provide clear introductions to tables, figures, and examples. 


Make table, figure, and example titles clear; make sure titles match 
the table/figure/example content. 


Do not put too much information in any one table column. Tables are 
meant to provide quick and easy-to-read information. If there is too 
much text, the user may not bother to read it. 


Use lots of examples. Good online and hardcopy writing requires 
extensive use of examples. 


Decide whether tables, figures, or examples should be formal or 
informal. Formal tables, figures, and examples have captions and 
symbol-names and are listed in the table of contents. When displayed 
by the Bookreader, formal tables, figures, and examples appear in a 
suitably-sized pop-up window. 


If you want a table, figure, or example to be informal, decide whether 
you want to create a pop-up window for it. You would want to create a 
pop-up window for an informal table, figure, or example if it is too wide 
(over 34 picas) or too long for display in the DECwindows Bookreader 
topic window. Do not use a pop-up window for an informal table, 
figure, or example if it easily fits in the topic window. 


Whenever you annotate a figure or example that is to appear in a 
pop-up window, make sure to include the annotation within the pop-up 
window. Otherwise, the annotation will be hidden by the figure or 
example. 


For more information on coding formal and informal tables, figures, and 
examples and creating pop-up windows, refer to Section 2.8.3. 
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2.6.6 Writing and Reviewing the Index 
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2.6.6.1 


Note: 


Creating an effective index for a book is vital to its success. This is 
especially important for online documentation because the index and table 
of contents are the only direct pathways to specific information in a book. 
To ensure that your book is indexed thoroughly and consistently, use the 
following guidelines for writing and reviewing the index. 


Every draft that you give to your editor should include an index. 
Your editor will edit the index thoroughly during the second pass 
edit. Therefore, you should schedule more editing time during the 
second pass edit. 


Writing the index 
For every chapter, create an index entry based on the information in each 
of the following items: 


¢ Chapter title 

e Every header - 

e Every subhead 

e Main topic of each section and subsection 


¢ Each paragraph that contains pertinent information within a section— 
even though the paragraph in which it is described is not preceded by 
a header 


For instance, the color function might be described in an untitled 
paragraph. Index the color function for it is pertinent information to 
the user. 


¢ Tasks and concepts 


Imagine the tasks. Think about the kinds of tasks people might do 
while using your book. Imagine doing the tasks. Try to figure out 
why you would be reading a particular paragraph, what you would be 
looking for. Then decide whether you have an appropriate index entry 
or pointer in the table of contents to guide the user to the information. 


To point out meaningful paths to critical information, describe a 
specific task or concept through the use of descriptive subentries. 
Meaningful paths to critical information can be shown to the user in 
this way. The following example describes all the information about 
files found in a chapter; 


— Files 


converting, 2-17 
displaying, 2-14 
organizing, 2-12 
sending, 2-14 

using FileView, 2-17 


2.6 Writing the Manual 


Note that there was not a section entitled Files within this book chapter. 
Individual paragraphs contained pertinent file information. 


e New terms 


¢ General subject matter of tables and figures, not specific items. It is 
particularily important to index informal tables and figures because 
they do not appear in the table of contents. 
Templates 


The preceding process assumes that descriptive titles are used for 
chapters, heads, and subheads. For books that use templates to 
document information such as routines, commands, or qualifiers, 
many of the headers are not descriptive. To thoroughly index template 
information, make sure you describe the task associated with the 
subject. The approach shown in the following four primary entries 
helps you to index a routine (and similar items) completely. 
DO_SOMETHING routine, 4-2 
2 Something 
doing, 4-2 
3 Doing something, 4-2 
4 Routines 
DO_SOMETHING, 4-2 
UNDO_SOMETHING, 4-15 
Hints 
Keep the following recommendations in mind: 


¢ Use at or an f after an entry to indicate a table or a figure, as shown 
in the following example. 


Document content aggregate, 6-6 
items in, 6-3t 
Note: Because page numbers are not listed in the online index, the ¢ 
or f will not appear in the online version of the manual. 


¢ Use cross references and synonyms whenever possible. This allows the 
user to find the same information under more than one primary entry. 


For example, the following index entries would point to the same 
information: 


e Allocating color 
¢ Colors 
e Hues 
¢ Make sure that cross references that are indicated really exist. 


¢ Instead of long page ranges, use subentries. Short page ranges can 
help the reader gauge the importance of a given entry (i.e., Mapping 
windows, 1-6, 3-16 to 3-18). 
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_Aprimary entry consists of a noun or a noun phrase. A noun is 


generally preferred. 


In some instances, an action is best described in a primary entry 

by a noun phrase consisting of a gerund and a noun (for example, 
Debugging programs). 

In other instances, a gerund best describes the task (for example, 

Scrolling). Use technically meaningful gerunds rather than vague 
entries such as Using and Inquiring. 


Note the use of gerunds throughout the index of The Chicago Manual 
of Style. 


Refer to the following for more help with indexing: 


The Role of the Index in Western Civilization, an internal document 
(written by Susan Hunziker) 


Index command procedure called Index-O-Matic that prints index 
entries within text (written by Don Topaz) 


Note: The Bookreader doesn’t go directly to the indexed term; it goes to 
the section heading of the section that contains the indexed term. 


2.6.6.2 Reviewing the Index 


Follow these index reviewing guidelines to ensure that your index is 
complete. When viewing your book online, check that your index is 
complete by doing the following: 


Do an index-based search. 


To do an index-based search, click on a term in the index and ensure 
that the corresponding display includes the appropriate information. 
Do this for all entries, if possible. 


Do a text-based search. 


To do a text-based search, pick a random paragraph, search for an 
important term, and go to the index (or the table of contents) to see 
whether the term is listed there. 


2.7 Converting Hardcopy Books to Online Format 


This section is only applicable to hardcopy books that have never been 
published in bookreader format. 


The cleanup required to convert a hardcopy book to online format consists 
of two phases. The first phase involves persuading VAX DOCUMENT to 
process a book’s source files for the online doctypes and BOOKREADER 
destination. The second involves ensuring that all parts of an online 
book are viewable by the DECwindows Bookreader and, time permitting, 
revising the source code such that the book’s information is more accessible 
and its display more pleasing. 
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Online cleanup is the procedure by which hardcopy-oriented DOCUMENT 
source files are made to comply with the online doctypes and DECwindows 
Bookreader software. The purpose of online cleanup is to produce a set 

of source files that can be successfully built for an online destination, 

the results of which can be successfully viewed by the DECwindows 
Bookreader. Online cleanup has no effect on how a set of source files 
builds for a hardcopy destination. 


Figure 2-1 depicts the general flow of online cleanup from the viewpoint of 
the writer. 


2-13 


Online Writing Guidelines 


2.7 Converting Hardcopy Books to Online Format 


Figure 2-1 Online Cleanup 
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To prepare for online cleanup, perform the following tasks: 
1 For a given book, reserve the following from the book’s CMS library: 
¢ Profile 
° All elements 
¢ All included files 
e XREF file (if any) 


2 Build the book for a hardcopy doctype. If the book does not build for 
a hardcopy doctype, it will not build for an online doctype. It may be 
difficult to debug errors if they are mistakenly attributed to the online 
software. 


3 Ensure that the editor has submitted to Graphic Services a revised 
art package for the book. (See the description of editorial tasks in 
Chapter 3.) Graphic Services converts all hardcopy art to online art (in 
SIX, PS, and DECW$BOOKFIG forms). You can proceed with online 
cleanup and online viewing without having the art available. When 
the editor informs you that the art is complete, you must copy it from 
Graphic Services to your build directory, build the book, and verify 
that all art is present and viewable. 


After performing as much online cleanup as is appropriate for your book 
and its schedule, you can rely on the trial-by-error method of bookbuilding. 
VAX DOCUMENT errors, as always, are evident in the bookbuild LOG 
file (and are described in Section 2.10.5); problems with the display of 

an online book can be uncovered with a bit of scrutiny (as discussed in 
Section 2.12). Most problems are easy to fix. 


2.8 Coding the Manual 


Several DOCUMENT coding conventions are required to successfully build 
a book for the ONLINE doctype and to make the output more readable. 
This section provides information on the coding conventions a writer 
should use to do the following: 


e Convert existing source files to be used by the DECwindows 
Bookreader 


e Code the source files for a new manual to be used online 


The following subsections describe areas of a book’s source files that 
typically need to be modified to build properly for online display. 
Certain steps ensure that all information in the book is accessible by 
the DECwindows Bookreader; these steps are listed as required in the 
text. Other steps enhance the appearance and improve the readability of 
a book; these tasks are listed as “Also Recommended” in the text. If you 
have enough time, you should perform these steps as well as all required 
ones. : 


If a particular step does not apply to your book, skip it; if you aren't sure, 
use the DCL SEARCH command on the book’s source files to determine 
whether it does. 
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Coding the Book’s Profile 


Examine the book’s profile, as follows. If time permits, perform the 
recommended tasks as well as the required ones. 


Required 


1 
2 


Place an <INDEX_FILE> tag just before the <ENDPROFILE> tag. 


If the book is—in its entirety—a glossary (that is, it is made up of 
<GTERM> and <GDEF> tags) or a message manual (that is, it is made up 
of <MSG> and <MSGS> tags), place the following tag after the <PROFILE> 
tag: 

<SET_ONLINE_TOPIC>(MASTER) 


These tags generate table of contents entries for master glossary 
volumes and messages manuale—books that do not have chapters 
and sections like other books. These table of contents entries take the 
following form: 


BADIF ... BADJOUCOM 
BADJOUCPOS ... BADJOUSTR 
or 

program ... protection 
protocol ... pure code 


For a manual with normal chapters and sections—even one that also 
contains messages and glossary entries—<SET_ONLINE_TOPIC>(MASTER) 
is neither required nor recommended. 


See Section 2.8.4 for a description of additional cleanup you must 
perform on glossary entries and messages. 


Aliso Recommended 


1 


For a manual that is not a message manual or master glossary, use 
the <SET_ONLINE_TOPIC> tag to establish the optimal topic granularity 
for the book. It is useful to place this tag after the <PROFILE> tag, if 
all chapters of the book have roughly the same number of <HEAD>, 
<HEAD2>, and <HEAD3> tage—and each subsection or sub-subsection 
generally contains % page or more of information. 


What is topic granularity? The DECwindows Bookreader displays 
pieces of a book, called topics, in a window. As you view a book with 
the DECwindows Bookreader, you “turn” its “pages” by clicking on 
the “Next Topic” and “Previous Topic” buttons. This is the fastest and 
most efficient way to maneuver about a book. Whenever the size of a 
topic exceeds the size of the topic window, you must manipulate the 
topic window's scroll bar to view. the entire topic. This can be slow and 
frustrating. 

By default, each <CHAPTER>, <HEAD1>, <APPENDIX>, <PART>, <PREFACE>, 
<PREFACE_SECTION>, <TITLE_PAGE>, <COPYRIGHT_PAGE>, and template 


page ends the previous topic and begins a new one. This level of 
granularity is almost always sufficient for most books. To establish a 
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finer topic granularity, place one of the following after the <PROFILE> 
tag: 

<SET_ONLINE_TOPIC>(HEAD2) 
<S8ET_ONLINE_TOPIC>(HEAD3) 

To establish a larger topic granularity, use: 
<8ET_ONLINE_TOPIC>(CHAPTER) 


Notes: You can place a <SET_ONLINE_TOPIC> tag anywhere in your book 
to switch topic granularity as seems fit. For these purposes, 
you can use any of the keywords illustrated above plus <SET_ 
ONLINE_TOPIC>(HEAD1), which restores the default. 


<SET_ONLINE_TOPIC> takes a single argument. 


2.8.2 Coding the Front Matter 


Examine the book’s front matter, as follows. If time permits, perform the 
recommended tasks as well as the required ones. 


Required 


1 Place the <CONTENTS_FILE> tag immediately before the <PREFACE> tag. 
If you must use the file-spec argument, use uppercase characters for 
the file specification. Otherwise, you may receive the device converter 
error message: 


&SDVC-E-NOCONTENTS, no contents file found 


2 Make sure that the front matter file contains a <TITLE> tag. If you 
omit the <TITLE> tag, the DECW$BOOKSHELF file produced by the 
online doctype uses the file name (without the extension) as the book’s 
title. 


3 Make sure that the <TITLE_PAGE> tag is the first tag in the book that 
generates text. 


Any text that appears before the <TITLE> tag—or appears in an 
included file pulled in (by either an <INCLUDE> tag or the DOCUMENT 
command line qualifier INCLUDE) before the <TITLE> tag—will cause 
an online bookbuild to fail with a cheery message: 

PAGE COORDINATION LOST:TeXpage =1, ChunkID=2; ABORT! 


&%DVC-E-BOOKABORT, aborting run -- book not created 
-DVC-I-input file is: 


4 Examine the “Conventions” section of the Preface. If it describes the 
appearance of interactive examples, be sure to distinguish between 
their appearance in hardcopy and online. For instance: 


In examples, system output (what the system displays) is shown i 
black. User input (what you enter) is shown in red. 


should be changed to: 
In examples, system output (what the system displays) is shown i 


black. User input (what you enter) is shown in red. 
In online versions, user input is shown in bold. 
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Also Recommended 


1 Convert any hard-coded references to chapters or sections of the book 
that may appear in the Preface so that they use <REFERENCE> tags. 
For instance: 


Chapter 3 describes how to bootstrap your Maine Hunting Shoe. 
<P> ; 


You’1l find exciting information about beets in Chapter 4. 
should become: 


<REFERENCE>(hunting_shoe_chap) describes how to bootstrap your Maine 
Hunting Shoe. 

<P> 

You’1l find exciting information about beets in 
<REFERENCE>(red_tuber_chap). 


2 If your front matter includes a “New and Changed Features” section, 
code it as follows: 


<PREFACE_SECTION>(New and Changed Features) 


This coding causes the DECwindows Bookreader to generate a table of 
contents entry for the “New and Changed Features” page by which a 
reader can instantly access new features information. The <PREFACE_ 
SECTION> tag also begins a new online topic. 


Without a table of contents entry, a new and changed features entry 
would likely be lost to the reader of an online book. (The code 
<HEAD1>(New and Changed Features\ ncf_sec) is common, but does not 
generate a table of contents entry.) 


3 Make sure that al] head tags within the Preface contain a symbol- 
name argument. For instance: 


<HEAD1>(Intended Audience\ intend_aud_sec) 


Contrary to ita requirements for heads in all other portions of a book, 
the online software does not require symbol-names for heads in a 
Preface. Regardless of this fact, you should place symbol-names in 
these heads, for consistency’s sake and for insurance. 


In yet another of those rare, challenging aspects of VAX DOCUMENT, 
head tags within the context of a Preface behave differently from 
head tags situated elsewhere in a book. VAX DOCUMENT does not 
generate table of contents entries for these heads, and (when building 
for hard copy) it is puzzled by any <REFERENCE> tag that is unfortunate 
enough to allude to their symbolic names. When building for online, 
this latter event generates an authentic device converter message. 


VOILA ERROR--The following symbols are undefined: 


pgid = 8, offset= 9085, symbol = 'INTEND_AUD SEC’ 
&DVC-E-OUTPUTFAIL, error writing to the output file 
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2.8.3 Coding Each Chapter, Appendix, and Part 


Examine each chapter, appendix, and part, as follows. If time permits, 
perform the recommended tasks as well as the required ones. 


Required 
1 Ensure that any use of the following tags contains a symbol-name 
argument: 


© <CHAPTER>, <APPENDIX>, or <PART> 
e All head tags 
© Tags introducing formal figures, tables, and examples 


If you omit a symbol name in one of these contexts, the tag translator 
protests: 


&STAG-E-LCL_MSG27, at tag <HEADI> on line 105 in file 
1111XYZ.SDML 
Symbol names are required in all header, figure, table, and example tags. 


If you ignore this message, you will obtain an error outburst during 
device conversion: 


VOILA ERROR--The following symbols are undefined: 
pgid= 9, offset = 4612, symbol = ‘DUMPSTYLE SEC’ 
pgid= 9, offset = 4570, symbol = ' INDUCING FAILURE SEC’ 
pgid= 9, offset = 4528, symbol = '’SDA_SYMBOL_TAB_SEC’ 
pgid= 9, offset = 4486, symbol = 'SDA_CONTEXT_SEC’ 


Note that this error resulted from a single undefined symbol, not four. 


2 Make sure that no <CHAPTER>, <APPENDIX>, or <PART> or head tag—or 
tag introducing a formal figure, table or example—is coded in such a 
way that the line breaks after the backslash (\). For instance: 


<HEAD1> (System Management and SDA\ 
sda_ sec) 


produces 


%TEX-RUNAWAY, Runaway ‘argument’ 

STEX-SHOWTOKEN, ’ {’ 

%STEX-W-EOP, Paragraph ended before the following completed: 
-TEX-W-DURING, Error occurred during a '’\topichunk’ 
~TEX-W-MISSINGRBRACE, Possible missing ’)}’ 
STEX-I-SHOWCONTEXT, ’ \par ’ 
&TEX-I-LINE, Error occurred on or around line number: 120 


3 Eliminate duplicate symbol names; they confuse the DECwindows 
Bookreader, and cause the following tag translator error: 


%TAG-E-DUPSYMBOL, at tag <SYMBOL_TABLE_ENTRY> on line 115 in file 
1111XYZ .8DML 
The symbol SDA_SEC is being defined twice. 
The earlier definition is replaced by the new definition 
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Replace all <FIGURE_SPACE> tags with a series of four <FIGURE_FILE> 
tags. ro all art generated by Graphic Services, use the following 
format: 


<FIGURE_FILE>(PS\ ZK-xxxx.PS\ nn) 

<FIGURE_FILE>(LN0O3\ ZK-xxxx.SIX\nn)_ 
<FIGURE_FILE>(LINE_PRINTER\ SPACE\ nn) 
<FIGURE_FILE>(BOOKREADER\ ZK-xxxx.DECW$BOOKFIG\ nn) 


ZK-xxxx represents the art control number portion of the file name; 
note that, although the file name is derived by the art number, 
the file name always includes a 4-digit number. For instance, if 

a figure has an art number of ZK-793, its online figure file name 
would be ZK-0793.DECW$BOOKFIG. (For newer art, there may 
be a letter appended to this 4-digit number: for example, ZK- 
0793a. DECW$BOOKFIG.) 


nn represents the vertical pica size of the figure—the size depends on 
the art file type and will not be the same in all <FIGURE_FILE> tags for 
a given figure. Graphic Services supplies the correct figure file names 
and vertical pica sizes for all DECW$BOOKFIG (the GE_PI column) 
and PS (the HC_PI column) art to you through your editor. To obtain 
LNO3 pica sizes, multiply the PostScript measurements by 1.08. 


Retain the original <FIGURE_SPACE> value in the LINE rendition of the 
<FIGURE_FILE> tag, but do not use the FULL_PAGE keyword. The text 
formatter will state: 


&%TEX-I-INFO, Figure is too large for a single page -- on page [42) 


%TEX-W-BADGLUE, 


Infinite glue. Attempting to recover 


STEX-I-SHOWCONTEXT, ’'...gegoal =\MACdimenA \fi \par ’ 
STEX_I-LINE, Error occurred at or around line number: 1821 


Note: 


For all screen image art that you have generated yourself using the 
Screen Capture and Image Manipulation Program (UTOX), use the 
following format: 


<FIGURE_FILE>(PS\ LPNnonnn.SDML-PS\ nn) 
<FIGURE_FILE>(LN03\ LPNnnnn.SDML-SIXEL\ nn) 
<FIGURE_FILE>(LINE_PRINTER\ SPACE \ nn) 
<FIGURE_FILE>(BOOKREADER\ LPNnnnn.SDML-BIN\ nn) 


The UTOX file name must begin with the 4-digit LPN of the book 

in which the UTOX art appears. Unlike art originated by Graphic 
Services and stored in DONVAN::ARTOUT, UTOX art is created and 
maintained by the writer and stored in a book’s CMS library or in the 
build directory, if there is no CMS library. nnnn represents the name 
of the figure; it can be longer than four characters. 


Any UTOX art that has been annotated and modified by 
Graphic Services uses the same file naming convention as 
other art generated within Graphic Services: that is, the file 


1 Note that, in the VMS documentation group, Graphic Services copies all figure files (DECW$BOOKFIG, 
SIX, and PS) from DONVAN::ARTOUT places them in CMS libraries on STAR. The logical ARTLIB is a 
search list pointing to CMS reference copy directories that contain usable online art. VMS writers are 
required to use ARTLIB: as a directory specification in each figure file name. GS operators define ARTLIB: 
locally to point to DONVAN::ARTOUT. | 
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name begins with the art control number. Annotated UTOX art 
is not stored in a book’s CMS library. 


If you have a wide figure, specify the WIDE keyword in both the 
<FIGURE_ATTRIBUTES> tag and the <FIGURE_FILE> tag. For example: 


<FIGURE>(An Interesting Figure\a_figure) 

<FIGURE_ATTRIBUTES>(WIDE) 

<FIGURE_FILE>(PS\ ARTLIB:ZK-xxxx.P8\ nh\ WIDE) 

<FIGURE_FILE>(LN03\ ARTLIB:ZK-xxxx.SIX\ nn\ WIDE) 
<FIGURE_FILE>(LINE_PRINTER\ SPACE \ nn\ WIDE) 
<FIGURE_FILE>(BOOKREADER\ ARTLIB:ZK-xxxx.DECW$BOOKFIG\ nn\ WIDE) 
<ENDFIGURE> 


The WIDE argument for wide figures affects the positioning of figures 
on the page for the hardcopy doctypes. Check the art control list for 
figures identified as WIDE. 


By this stage in online cleanup, you will already have had your editor 
submit an art package for the book to Graphic Services. If the art is 
not ready, you can and should proceed with online cleanup. You can 
build and view a book without correct values for figure file name and 
vertical pica size. This will make it easier and quicker for you to build 
and view the book later, when the artwork is available. 


When the artwork is ready, follow the instructions in Section 2.10.1. 


Perform this step for <ICON_FILE> and <MARGIN_ICON> tags as well 
as for <FIGURE_FILE> tags. 


Check formal figures, tables, and examples. 


Formal figures, tables, and examples have captions and symbol- 
names. The table of contents contains an entry for each formal figure, 
table, and example in a book. When displayed by the DECwindows 
Bookreader, formal figures, tables, and examples appear in a suitably- 
sized popup window (separate from the topic window). 


Wherever there is a formal figure, table, or example, there must be 
a <REFERENCE> tag that uses its symbol-name. This is tricky. In 
hardcopy documents, it is easy to omit the <REFERENCE> tag, because 
the formal figure automatically appears in the text just about in the 
position you place it in the SDML code. 


In online documents, formal figures, tables, and examples will 
DISAPPEAR WITHOUT A TRACE!!! if their symbol names do 

not appear in a <REFERENCE> tag. You will be not be able to page 
through the online document sequentially and access the figures, 
tables, and examples; they will only be accessible through the table of 
contents. Section 2.12 offers some suggestions on how to trap this type 
of problem. 


Check informal figures, tables, and examples. Informal figures, tables, 
and examples may have a caption, but they never have associated 
symbol-names. 
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For online processing, informal figures, tables, and examples can stay 
the way they are. Don’t touch them, unless: 


e The informal figure, table, or example is too wide (over 34 picas) 
for display in the DECwindows Bookreader topic window. (You 
would notice this while viewing the book, but you can make a 
good guess if you know the material in the book.) A wide informal 
figure, table, or example forces the reader of an online book to 
resize the topic window or use the horizontal scroll bar to view the 
entire figure, table, or example. 


e The bookbuild aborts due to an ’ TEX-E-NOROOM, Exceeded 
memory capacity’ TeX error that you can trace to a section 
containing many long informal figures, tables, or examples. 


e The bookbuild succeeds, but viewing the figure, table, or example 
with the DECwindows Bookreader is aesthetically displeasing. 


You should first examine the figure, table, or example to see whether 
it deserves treatment as a formal figure, table, or example. If so, the 
process is fairly simple: 


e Adda caption and a symbol-name to the <FIGURE> tag 


¢ Add a sentence pointing to the figure, table, or example, using a 
<REFERENCE> tag that references the symbol-name 


If the figure, table, or example is not worthy of formal treatment, you 
can force the DECwindows Bookreader to create a pop-up window for 
it by using the <ONLINE_POPUP> tag sequence. This process is also 
quite simple: 


e Place an <ONLINE_POPUP>(nnn) tag immediately before the 
<FIGURE>, <TABLE>, <CODE_EXAMPLE>, <INTERACTIVE>, <DISPLAY>, 
<EXC>, or <EXI> tag. The <ONLINE_POPUP> tag takes a single 
argument, but the argument can contain more than one word. This 
argument identifies the contents of the DECwindows Bookreader 
hotspot, so it is worth being brief and to-the-point: “Figure,” 
“Table,” “Example,” and “Example Callouts” are good argument 
values. 


e Place an <ENDONLINE_POPUP> tag after the ending tag of the figure, 
table, or example. Note that it seems good to leave the <EXTEXT> 
portion of an <EXI> or <EXC> example out of the section bracketed 
by the online pop-up tags. 

Do not enclose tags that generate heads within an online pop-up 
sequence. This include <EXAMPLE_SEQUENCE> and <DESCRIPTION> 
tags, as well as the normal head tags. Also, do not nest online pop- 
up sequences; you cannot place formal tables, figures, examples, 
and online pop-up sequences within an online pop-up sequence. 

If you miscode an online pop-up sequence by omitting an 


<ENDONLINE_POPUP> tag or by nesting online pop-ups, you will 
get the following type of error: 
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VOILA ERROR--The following symbols are undefined: 
offset = 921, symbol = ' DECW_SEMIFORMAL 13’ 


pgid = 


53, 


Note that the online pop-up (semiformal) symbol names contain 

a sequence number. You can find the troublesome online pop-up 
sequence somewhat easily by using the DCL SEARCH command 
to search for the phrase "<online_popup>" in your files in the order 
in which they appear in the book; In the example above, the 13th 
online pop-up sequence found by the DCL SEARCH command is 
the culprit. 


7 Make sure that index entries referring to information within a given 


section appear within that section and not before its head tag. 


Aiso Recommended 


1 


Make sure that index entries are not coded within a formal figure, 
table, or example—or within any online pop-up sequence. If a reader 
clicks on an index entry resulting from this type of coding, the 
DECwindows Bookreader displays the pop-up window alone. Without 
additional context, such index entries are not useful to a reader. 


If your book contains more than one section with the same name, you 
should be aware that identical index entries in each section may result 
in confusing pointers from the online index. In this situation, you 
should consider either: 


¢ Renaming the sections so that they all have unique names 


¢ Using subentries to qualify the index entries such that it is clear 
to the user how they differ 


Make sure that each <CHAPTER>, <APPENDIX>, and <PART> tag is 
followed by some text. Otherwise, the DECwindows Bookreader 
displays only the title of the chapter, appendix, or part in the topic 
window. You may want to delete the first <HEAD1> tag in the chapter, 
appendix, or part; or you may decide to add an overview paragraph 
before the first <HEAD1>. 


Certain coding conventions that produce fine hardcopy output do not 
work in a predictable way for online output. Investigate the following 
suspect practices: 


¢ Use of multiple, adjacent <P> tags to create space in a hardcopy 
document. This code results in unattractive online output. Remove 
the extra <P> tags. 


© Use of <P> tags before <TABLE>, <LIST>, <FIGURE>, and similar tags 
also produces strange and ugly online output. Remove the <P> tag. 


© Use of the <LINE> tag to force a line break based only on the 
appearance of a hardcopy book. Be sure that you want the line 
break in both the hardcopy and online versions of the book. If you 
need a line break only in the hardcopy book, use the tag <FINAL_ 
CLEANUP>(LINE_BREAK). 


Note: The <PAGE> and <FINAL_CLEANUP> tags are disabled for the 


online doctypes. 
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5 Informal examples containing callouts and the accompanying callout 


list provide an excellent opportunity of using the <ONLINE_POPUP> 

tag in a creative way. The annotated example can appear within one 
online popup sequence, and the callout list can appear in another. This 
coding strategy allows the reader of the online manual to see both the 
example and the associated callouts on the screen at the same time. 


The online software assumes that a <FOOTREF>(n) tag in text refers 

to the most recent occurrence of a <FOOTNOTE>(n\...) tag in text. If 

the online software gets confused (for instance, there is no previous 
<FOOTNOTE>(n) tag in text), the tag translator will alert you to this 

situation with: 


%TAG-W-LCL_MSG26, at tag <FOOTREF> on line 32 in file 


Possible problem with footnotes 
7 You cannot use more than one <FOOTREF> tag in a header. If you do, 


the device converter exclaims: 


VOILA ERROR--The following symbols are undefined: 
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offset = 181, symbol = ' DECW_HEADFN 2 1 5’ 


In this case, the “2” is the footnote callout (<FOOTREF>(2)); “1” indicates 
the first header footnote in the book; and “5” is a number used 
internally by the online software. 


You can, however, use multiple arguments to a single <FOOTREF> tag in 
a header. For instance: 


<HEAD1> (Using Postscript<FOOTREF>(R\1) Printers) 
<FOOTNOTE_TEXT> (R\ Post script<SPECIAL_CHAR>(register_symbol) is a 
registered trademark of Adobe Systems Incorporated.) 
<FOOTNOTE_TEXT>(1\For more information, see...) 


However, the online software assumes that the <FOOTNOTE_TEXT> tags 
follow the head tag in the order in which they appear in the <FOOTREF> 
tag. 


Make sure no <REFERENCE> tag uses the \ VALUE qualifier needlessly. 


The DECwindows Bookreader defines the contents of a hotspot 
(identified by the Bookreader by a rectangular outline) from 
information supplied in the <REFERENCE> tag. If you use 
<REFERENCE>(SYMBOL_NAME), the hotspot includes the identifying 
reference (be it “Symbol,” “Table,” “Chapter,” “Section,” or whatever). 
If you use Section <REFERENCE>(SYMBOL_NAME\ VALUE), the word 
“Section” appears outside of the hotspot. 

Search for the \ VALUE qualifier in your source files. You should not 
change legitimate uses of the qualifier. For instance, the following code 
is correct and necessary: 

Excessive discussion of the /OLFACTORY, /NOSTRILS, and /NASAL 
qualifiers appears in Sections <REFERENCE>(ncee_sec\ value) and 
<REFERENCE>(more_nose_sec\ value), and <REFERENCE>(snore_nose_sec\ value). 


However, if the \ VALUE qualifier is unneeded, remove both it and the 
identifying reference word. 
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2.8.4 Coding Glossaries and Messages 


If your book contains glossary entries (identified by the <GTERM> tag) and 
/or messages (identified by the <MSG> or <MSGS> tag), perform the following 
required tasks. 


Required 


1 Make sure that the <GLOSSARY> tag has a symbol-name argument. 
Note that the symbol-name is the second argument. For instance, you 
may use: 


<GLOSSARY> 


If you omit the symbol-name in a <GLOSSARY> tag, VAX DOCUMENT 
will generate the following error for each entry in the glossary: 


%STAG-E-LCL_MSG27, at tag <HEADI> on line 105 in file 
1111GLS.SDML 
Symbol names are required in all header, figure, table, and example tags. 


2 Ifthe manual uses the <SET_ONLINE_TOPIC>(master) (as discussed in 
Section 2.8.1), examine each <GTERM>, <MSG>, or <MSGS> tag for 
embedded tags. 


An embedded tag looks like this: 

<GTERM> (<QUOTE>(lookaside) list) ) 

or this: 

<MSG> (Line too long by <EMPHASIS>(nnnn) picas) 


If you discover an embedded tag, use the <DELAYED> tag to delay tag 
translation. (The delay helps the online software produce table of 
contents entries for glossary terms and messages.) 


Thus, you would render the above entries as follows: 
<GTERM> (<delayed> (<QUOTE>(lookaside)) list) ) 
or 


<MSG> (Line too long by <delayed>(<EMPHASIS>(nnnn)) picas) 


2.9 Using Tools to Facilitate Online Builds 


There are a few tools available over the network that check DOCUMENT 
source code, flag coding practices that may pose problems for the online 
software, and—in certain instances—actually change the source code so 
that it adheres to some of the requirements of the online software. 


You can choose to perform all of the online cleanup for a book manually, 
or you can have one of those programs perform some of it for you. If you 
take the latter course, you should be aware that none of these programs is 
officially supported or maintained, and none is designed to take care of all 
potentially problematic coding practices. It is quite possible that your book 
is not complex enough to warrant using the tool, or is so complex that the 
tool will break. 
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Note: 


If you do choose to use one of these programs, make absolutely sure 
that you have saved a copy of your DOCUMENT source files somewhere 
before unleashing the program. You may need to back out of some of the 
changes it makes, or you may need to restore a portion of the old file. 
(This is common sense, not a criticism of the quality of the programs or 
the diligence of their creators in testing their effects.) 


Notes conference CLOSET::ONLINE_BOOKBUILDING mentions these 
tools in Topics 16 and 17. 


To reiterate, neither of these programs is supported. The 
descriptions which follow accurately reflect the operation of 

the latest posted versions. As of this writing, neither version of 
ONLINE_CLEANUP.COM have been verified to work with Version 
2.0 of the DECwindows bookreader. 


2.9.1 ONLINE _CLEANUP.COM 
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ONLINE_CLEANUP.COM (Topic 16) is a command procedure that creates 
and executes a BLISS image that performs the following tasks: 


1 Automatically generates a symbol-name argument for those <HEAD«x> 
tags that do not already have a symbol-name argument. 


2 Automatically replaces all <FIGURE_SPACE>(nn) tags with a set of four 
<FIGURE_FILE> tags of the following form: 
<FIGURE_FILE> (PS\ ZK-<fig.PS\ nn) 
<FIGURE_FILE>(LNO3\ Z2K-<fig.SIX\nn) 


<FIGURE_FILE> (LINE\ SPACE\nn) 
<FIGURE_FILE> (Bookreader\ ZK-<fig .DECWSBOOKFIG\ nn) 


3 Produces a file, named ONLINE-CLEANUP.LOG, that lists places 
where an inappropriately-placed <P> tag may produce unattractive 
Bookreader output and points to other potentially troublesome code. 


Use of ONLINE_CLEANUP.COM is subject to the following restrictions: 
1 VAX BLISS must be installed on the system on which it executes. 


2 It requires a profile name. In other words, you can only use it to 
convert an SDML file when that file is listed within a profile as an 
element. 


3 All <P> tags in the source files upon which it operates must be at the 
beginning of a line. 

4 All tags and their arguments must reside on the same line. This 
restriction also applies to <HEADx> tags. 

§ ONLINE_CLEANUP.COM will process all files listed in the profile, 
even those listed within a comment. 


6 If one or more <FIGURE_FILE> tags already exist within a figure, 
ONLINE_CLEANUP.COM does not check to see whether all four 
<FIGURE_FILE> tags are there. 
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ONLINE_CLEANUP.COM is available at the following location: 
BULOVA: :DOCD$: [ONLINE] ONLINE_CLEANUP .COM 
To run it, use the following DCL command line syntax: 


$ @ONLINE_ CLEANUP full-profile-spec source-file-directory 


2.9.2 Alternate ONLINE_CLEANUP.COM 


The alternate ONLINE_CLEANUP.COM (Topic 17) is strictly a DCL 
command procedure, derived from the original version of ONLINE_ 
CLEANUP.COM, and performs many of the same tasks, and is subject 
to many of the same restrictions. It creates symbol-name arguments for 
section heads, but replaces <FIGURE_SPACE>(n) tags with a single <FIGURE_ 
FILE> tag, of the form: 


<figure_file>(Bookreader \ xxxxxx\n) 


Unlike the original version, it can recognize <P> tags at the end of a line— 
a@ common occurrence in files that were originally translated from DSR 
with the DSR-to-SDML converter. 


It reports various potentially-troublesome uses of the <P> tag in a file 
named ONLINE_CLEANUP_profile_filename.DAT. Because it is a DCL 
program, it can be very slow. 


The alternate ONLINE_CLEANUP.COM is available at the following 
location: 


REORG: :USER2$: [MURRAY] ONLINE_CLEANUP .COM 

To run it, use the following DCL command line syntax: 

$ @ONLINE_CLEANUP profile-name.SDML directory-name 
You can also submit the procedure as a batch job. 


2.9.3 The Book Verification Utility 


After you build a book for online, you can use the Book Verification Utility 
to check figures, popups, topics, cross-references, the Table of Contents, 
and the index. After analyzing the book, the utility creates a log file with 
the extension ANALYSIS. 


The utility can be copied from CDROM::BVU010.A and installed with 
VMSINSTAL. If you are on a cluster, your system manager will have to do 
install it for you to replace the DCL tables. 


Once the utility is installed, you can use the BOOKVERIFY command to 
run the utility, as follows: 


e ri cessl a ll’oucSosak Va thw Gecasttual Waid exeelo a eenaty ANALYSIS 
file: 


$ BOOKVERIFY filename.DECWSBOOK [/OUTPUT=output-file] 
The /OUTPUT qualifier changes the name of the ANALYSIS file. 
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¢ To send output to the terminal only: 
$ BOOKVERIFY/NOOUTPUT filename. DECWSBOOK 
© Tosend all the output to a file. 
$ BOOKVERIFY/FULL filename.DECWSBOOK /OUTPUT=output-file 


The CLOSET::ONLINE_BOOKBUILDING conference contains 
announcements and information on the Book Verification Utility. 


Note: As of this writing, the Book Verification Utility does not work with 
books built for Version 2.0 of the DEC windows bookreader. 


2.10 Building an Online Book 


This section describes the steps involved in building an online book, 
including: 


© Copying art files to the build directory 
e Building the DECW$BOOK file 
* Building the DECW$BOOKSHELF file 


¢ Diagnosing online processing errors 


2.10.1 Copying Art Files to the Build Directory 


When the artists complete work on the art package, they will make the 
art available at DONVAN::ARTOUT and inform the editor. The editor will 
relay to you the file names and vertical pica sizes of all figure files in the 
book. It is then your responsibility to do the following: 


¢ Insert the correct figure name and vertical pica size in every <FIGURE_ 
FILE>, <ICON_FILE>, and <MARGIN_ICON> tag in your book. 


¢ Copy the appropriate art files from DONVAN::ARTOUT to your build 
directory so that they will be available for DOCUMENT during the 
online bookbuild.? 


e Build the book for an online doctype, as discussed in Section 2.10.2. 


You can (and should) build a converted book, even though all art files may 
not be available. If it cannot find a figure file, VAX DOCUMENT generates 
the following warning and continues: 


%DVC-W-SPECIALERROR, error in \special 
voila: plotfile ZK-1922.DECWSBOOKFIG 
-DVC-W-FIGFILOPN, cannot open figure file 

“DVC-I-INPUTFILE, input file is 
WORK6: [ROTTEN] 4556PRO.DVI_BOOKREADER 
-DVC-I-ONPAGE, on page [46] 


* Note that, in the VMS documentation group, Graphic Services copies all figure files (DECW$BOOKFIG, 
SIX, and PS) from DONVAN::ARTOUT places them in local CMS libraries on STAR. The logical ARTLIB is 
a search list pointing to CMS reference copy directories that contain usable online art. VMS writers are 


required to use ARTLIB: as a directory specification in each figure file name. GS operators define ARTLIB: 
locally to point to DONVAN::ARTOUT. 
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This error is easily rectified by copying the figure, once it is available, to 
the build directory. 


In certain circumstances, you may obtain the following error: 


%DVC-W-SPECIALERROR, error in \special 
voila: plotfile ZK-1933.DECWSBOOKFIG 
-DVC-W-FIGFILOPN, cannot find figure image in figure file 
-DVC-I-INPUTFILE, input file is 
WORK6: [ROTTEN] 4556PRO.DVI_BOOKREADER 
-DVC-I-ONPAGE, on page [46] 


This error indicates that the referenced DECW$BOOKFIG file does not 
contain a usable figure. You should notify Graphic Services of any figure 
file that causes this problem. 


2.10.2 Building the DECW$BOOK File 


To initiate an online bookbuild, use the following command: 


§ DOCUMENT profile name online-doctype BOOKREADER /CONTENTS / INDEX/LIST/MAP /KEEP 


Note: 


The online-doctype can be either ONLINE.REFERENCE or 
ONLINE.HANDBOOK, as determined for your document. 


The /CONTENTS and /INDEX qualifiers are required and correspond 
to <CONTENTS_FILE> and <INDEX_FILE> tags in the book, as discussed in 
Sections 2.8.1 and 2.8.2, respectively. 


The /LIST and /KEEP qualifiers ensure that interim files and a list file are 
retained after DOCUMENT processing, just in case you need to report an 
error. 


The /MAP qualifier is required of writers in the VMS documentation 
group. DOCUMENT .MAP_LIS files from a successful online bookbuild 
must be checked into the CMS libraries of all VMS books.® 


You may need to use /SSYMBOLS«xxx_BOOKNAMES during your 
hardcopy bookbuilds. VMS_BOOKNAMES, LP_BOOKNAMES, 
and the other booknames files contain a line that includes 
CUPSONLINE_DEFS.GDX, a file that allows the hardcopy 
doctypes to recognize the online-specific tags and keywords. 

If this file is not included in a booknames file available to 
your group, the qualifier phrase /SYMBOLS«DOCS$LOCAL_ 
FORMATS:CUPSONLINE_DEFS.GDX should be used. 


A successful bookbuild for an online doctype and BOOKREADER 
destination is one that has no -E-, -W-, or -F- errors (you can search 

the LOG file for these characters). If all converted art files are not yet 
available, you can proceed with viewing the book, even though there may 
be device converter errors (DVC-W-SPECIALERROR) that signify one or 
more missing figure files. 

The products of a successful online bookbuild are the output file 
(DECW$BOOK) and a DECwindows Bookreader bookshelf entry file 
(.DECW$BOOKSHELF). 


* Automatic document set building, as used in the VMS documentation group, requires the MAP LIS file. 
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2.10.3 Building the DECW$BOOKSHELF File 


The ONLINE.SHELF doctype allows users to define the bookshelf 
structure for a document set in a ecures file by using the following 
DOCUMENT tags: 


e <SHELF_CREATE>(shelf-symbol-name\ filechawie) and <ENDSHELF_ 
CREATE> 


Creates a new shelf (DECW$BOOKSHELF) file. 
¢ <SHELF_REF>(book-symbol-name\ file-name) 

Specifies an existing shelf file in a library or in another shelf file. 
© <BOOK_REF>(book-symbol-name\ file-name) 

Specifies books in a library or in shelf files. 


For further explanation of the proper use of these tags, see the description 
of the ONLINE.SHELF doctype. 


For more information, see Coding Documentation Source Files for the 
DECwindows Bookreader. 


2.10.4 Licensing the DECW$BOOK file 


Please refer to Coding Documentation Source Files for the DECwindows 
Bookreader. 


2.10.5 Diagnosing Online Processing Errors 


Tag Transiator Errors 
a 


This section lists messages you may encounter in the course of building 
your book with an online doctype. Listed messages appear in three 
categories: 


e Tag translator warnings and errors (prefixed by %TAG). 
¢ Text processing warnings and errors (prefixed by %TEX). 


¢ Device converter warnings and errors (prefixed by %DVC). VOILA 
ERRORS belong to this category. 


If you come across processing errors you cannot resolve, seek the 
assistance of a systems analyst. 


STAG-E-DUPSYMBOL, at tag <SYMBOL_TABLE_ENTRY> on line 115 in file 
1111XYzZ .SDML 


The symbol SDA_SEC is being defined twice. 
The earlier definition is replaced by the new definition 
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You have used the same symbol name in more than one <HEADx> tag. 
This will confuse the DECwindows Bookreader; you should always use 
unique symbol names. 
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%TAG~W-LCL_MSG26, at tag <FOOTREF> on line 32 in file 
4556SDA.SDML 
Possible problem with footnotes 


You've used a <FOOTREF> tag that references a footnote number for which 
there is no corresponding <FOOTNOTE> tag. 


%TAG-E-LCL_MSG27, at tag <HEADI> on line 105 in file 
1111XYZ.SDML 
Symbol names are required in all header. figure, table, and example tags. 


Perhaps you have omitted the symbol name argument to the <HEAD1> tag 
at line 105. You would be given a similar error for neglecting to put a 
symbol name in a <CHAPTER>, <HEAD2>, or <PART> tag, or other header tag. 


STAG-E-TAG FAILS, The tag translator has detected a fatal error 
~TAG-F-EOFARGLIST, End of file encountered while searching for closing 
parenthesis. See argument list of tag <TAG_DIAGNOSTIC> on 
line 14 of file 4556SDA.SDML 


Perhaps you have misspelled a keyword (for instance, HEAD1, CHAPTER) 
to the <SET_ONLINE_TOPIC> tag at line 14. 


STAG-W-TAGNOTDEF, at text on line 6 in file 
4490GLS .SDML 
Tag <_DECW_TOCTERM> is undefined 


You are using <SET_ONLINE_TOPIC>(master) and the device converter has 
come across a <GTERM>, <MSG>, or <MSGS> tag that contains an embedded 
tag. You must put the embedded tag and its arguments into a <DELAYED> 
tag. 


Text Processor Errors 


STEX-I-INFO, Figure is too large for a single page -- on page [42] 
%TEX-W-BADGLUE, Infinite glue. Attempting to recover 
%TEX-I-SHOWCONTEXT, ’...gegoal =\MACdimenA \fi \par ’ 
%TEX_I-LINE, Error occurred at or around line number: 1821 


A <FIGURE_FILE> tag specifies a vertical pica size that is too long for the 
online software. Check for the FULL_PAGE keyword in a <FIGURE_FILE> 
tag; it is illegal. 


Search the TEX file around line 1821 to obtain some context for the error 
in the SDML file. 


STEX-E-NOROOM, Exceeded memory capacity: 

-TEX-I-MEMORYSIZE, Main memory size = 131072 words 

STEX-I-LINE, Error occurred on or around line number: 3442 
STEX-I-SHOWCONTEXT, ’ CLRW UCcB\ $W\_D’ 

%TEX-I-SHOWCONTEXT, ' L\_FLAGS (R5) + Clear adapter mapping bit’ 
STEX-I-FILENAME, ’WORK6: [BUTTLAR. TRASH) 45568DA. TEX; 30’ 


This error usually results from an extremely long code example, figure, 
or table, or a series of long code examples, figures, and tables in a single 
section or chapter. The solution is threefold: 
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e If possible, make long examples, figures, and tables formal, or place 
them within an online popup tag sequence. 


¢ Make sure that long examples contain a sufficient number of and 
proper placement of <VALID_BREAK> tags. 


¢ Make sure that long and complex tables contain a sufficient number of 
and proper placement of <VALID_TABLE_ROW_BREAK> tags. 


2 

E %STEX-W-RUNAWAY, Runaway ‘argument’ 
%STEX-SHOWTOKEN, ’ {’ 
STEX-W-EOP, Paragraph ended before the following completed: 
-TEX-W-DURING, Error occurred during a ’\topichunk’ 
~TEX-W-MISSINGRBRACE, Possible missing ’ }’ 
%TEX-I~SHOWCONTEXT, ’ \par ’ 
STEX-I-LINE, Error occurred on or around line number: 120 


Possibly a symbol-name has been separated from the header tag for which 
it is defined. For instance, the following code generates this error: 


<HEAD1> (System Management and SDA\ 
sda_ sec) 


Search the TEX file around line 120 to obtain some context for the error in 
the SDML file. 


G %TEX-W-RUNAWAY, Runaway ‘definition’ 
%STEX-I-SHOWTOKEN, '->Inducing a System Failure] [][] [0] (0) (0) [(]{]’ 
%TEX-E-NOROOM, Exceeded memory capacity: 
~TEX-I-MEMORYSIZE, Main memory size = 131072 words 
&%TEX-I-SHOWCONTEXT, ’...lure})(){](O] [OJ [OJ [J (J)(’ 
%TEX-I-SHOWCONTEXT, ’ 2:8) (0) (0) (4) [16] [2] [0] [O}) [::’ 


This error usually results from an extremely long code example, or a series 
of long code examples, figures, and tables in a single section or chapter. 
The solution is twofold: 


¢ If possible, make long examples, figures, and tables formal, or place 
them within an online popup tag sequence. 


e Make sure that long examples contain <VALID_BREAK> tags. 
Device Converter Errors 


&SDVC-W-SPECIALERROR, error in \special 
voila: plotfile ZK-1922 .DECWSBOOKFIG 
-DVC-W-FIGFILOPN, cannot open figure file 

-DVC-I-INPUTFILE, input file is 
WORK6 : [ROTTEN] 4556PRO.DVI_BOOKREADER 
~DVC-I-ONPAGE, on page [46] 


The specified figure file does not exist. Usually this means that the file 
has yet to be copied from DONVAN::ARTOUT:. Sometimes it means that 
the figure file name is incorrect. 
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2 %DVC-W~-SPECIALERROR, error in \special 
voila: plotfile ZK-1933 .DECWSBOOKFIG 
~DVC-W-FIGFILOPN, cannot find figure image in figure file 
-DVC-I-INPUTFILE, input file is 
WORK6: [ROTTEN] 4556PRO.DVI_BOOKREADER 
~DVC-I-ONPAGE, on page [46] 

The specified figure file does not contain‘a properly-encoded figure. 

Contact Graphic Services. 

PAGE COORDINATION LOST:TeXpage =1, ChunkID=2; ABORT! 
%DVC-E-BOOKABORT, aborting run -- book not created 
-~DvC-I-input file is: 

This error is a symptom of one of the following DOCUMENT coding errors: 

¢ Your front matter file contains text prior to the <TITLE> tag. 

¢ You have used an <INCLUDE> tag that results in text being inserted 
before the <TITLE> tag (or you have used the (INCLUDE qualifier to 
the DOCUMENT command line, with the same result). 

e You are using <SET_ONLINE_TOPIC>(master) and the device converter 
has come across a <GTERM>, <MSG>, or <MSGS> tag that contains an 
embedded tag. You must put the embedded tag and its arguments into 
a <DELAYED> tag. 


VOILA ERROR--The following symbols are undefined: 
pgid= 9, offset = 4612, symbol = ‘’DUMPSTYLE SEC’ 
pgid= 9, offset = 4570, symbol = ‘INDUCING | FAILURE_. SEC’ 
pgid= 9, offset = 4528, symbol = ’SDA __ SYMBOL , TAB SEc’ 
pgid= 9, offset = 4486, symbol = ‘SDA | CONTEXT _; SEC’ 
%DVC-E-OUTPUTFAIL, error writing to output file 


You have forgotten to place a symbol-name argument in a <CHAPTER> 
or <APPENDIX> tag, <HEAD«x> tag, formal figures, tables, or example, or 
<PART> tag. Check the LOG file for the tag translation error: 


&STAG-E-LCL_MSG27, at tag <HEAD1> on line 105 in file 
1111XYZ.SDML 


Symbol names are required in all header, figure, table, and example tags. 
a VOILA ERROR--The following symbols are undefined: 


pgid = 8, offset= 9085, symbol = ‘INTEND _AUD_SEC’ 
&SDVC-E-OUTPUTFAIL, error writing to the output file 


In a <REFERENCE> tag, you have placed a symbol-name that is not used by 
the online DOCUMENT software. This particular error can happen if you 
reference a symbol-name defined in a head tag within a Preface. 
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VOILA ERROR--The following symbols are undefined: 
pgid = 10, offset= 1549, symbol = ’'-' 
SDVC-E-OUTPUTFAIL, error writing to output file 


Check earlier in the LOG file for a tag translator error. This particular 


error resulted from the continuation processing after the tag translator 
error: 


%TAG-W-LCL_MSG26, at tag <FOOTREF> on line 32 in file 
4556SDA.SDML 


Possible problem with footnotes 


VOILA ERROR--The following symbols are undefined: 


pgid = 12, offset = 181, symbol = ' DECW FOOTNOTE 3 1 5’ 
%DVC-E-OUTPUTFAIL, error writing to output file 


You have miscoded a footnote in text (outside of a header tag). 
Break down the symbol name: DECW_FOOTNOTE_X_N1_N2: 


X is the character that appears in the <FOOTNOTE> or <FOOTREF>. 


¢ N1 is the sequence number of the text footnote in the book; for 
instance, ’7’ would indicate the seventh text footnote in the book. 
(Use the DCL search command to help locate the NI st footnote.) 


¢ N2 is a numeric indicator of the element of text (as used internally by 
VAX DOCUMENT). 


VOILA ERROR--The following symbols are undefined: 


pgid = 12, offset = 181, symbol = ' DECW HEADFN 2 1 5’ 
%DVC-E-OUTPUTFAIL, error writing to output file 


You have a miscoded footnote inside a header tag. This usually occurs 
when there is more than one <FOOTREF> tag in a single header. 
Break down the symbol name: DECW_HEADFN_X_N1_N2: 


X is the character that appears in the <FOOTNOTE> or <FOOTREF>. 


e N1 is the sequence number of the header footnote in the book; for 
instance, 7’ would indicate the seventh header footnote in the book. 
(Use the DCL search command to help locate the N1st footnote.) 


¢ N2 is a numeric indicator of the element of text (as used internally by 
VAX DOCUMENT). 


VOILA ERROR--The following symbols are undefined: 


pgid = 53, offset = 921, symbol = ' DECW SEMIFORMAL 13’ 
R8DVC-E-OUTPUTFAIL, error writing to output file 


You have miscoded an online popup tag sequence. Look for: 
¢ A missing <ENDONLINE_POPUP> tag. 


e An online popup tag sequence within another online popup tag 
sequence or within a formal figure, table, or example. 
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¢ A formal figure, table, or example within an online popup tag 
sequence. 


Note that the DECW_SEMIFORMAL symbol errors are identified by 

a sequence number that indicates the place of the errant online popup 
within the online book. You can use the DCL SEARCH command 
(searching for “<online_popup”) to expedite finding the problem. As you 
search each source file in the correct sequence, the nth online popup will 
likely be the cause of the DECW_SEMIFORMAL_n» error. 


2.11 Preparing to View an Online Book 


Even though you have successfully built your book, you cannot 
automatically assume that you can successfully view it in its entirety 
online. As you would a hardcopy book draft, you must check the online 
book for missing or misformatted information, display problems, and other 
flaws. To check an online book, you need access to a workstation running 
DECwindows. 


You must also run the DECwindows Bookreader. It is perfectly sufficient 
to run the Bookreader on the workstation where you will be displaying 
the online books. However, if you are fortunate enough to have an account 
on a larger VAX or VAXcluster that is running DECwindows, you can 

run the DECwindows Bookreader remotely on the larger machine. (The 
Bookreader performance is immeasureably more impressive when run on 
a large memory machine.) 


There are four tasks you must perform on the system from which you will 
be running the Bookreader to set up the Bookreader environment. They 
are as follows: 


1 Set up an online review directory. Simply use the DCL CREATE 
/DIRECTORY command to create a subdirectory in which you can 
store the file LIBRARY. DECW$BOOKSHELF and your DECW$BOOK 
files. For example: 


$ CREATE/DIR [.ONLINE_BOOKS] 


2 Define the logical name DECW$BOOK to point to your online review 
directory. For example: 
$ DEFINE DECWSBOOK WORK15S: [DRENCH .ONLINE_ BOOKS] 


It may be worthwhile to include this line in your LOGIN.COM 
procedure. 

3 Create the file LIBRARY. DECW$BOOKSHELF in your online review 
directory. Use an editor, or issue commands such as the following: 


$ SET DEFAULT WORK1$: [DRENCH.ONLINE BOOKS) 
$ CREATE LIBRARY .DECWSBOOKSHELF 


(ESRr7z) 
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Once you have set up the Bookreader environment, you can move to the 
online review directory the files of the online books you want to view. 
Perform the following steps: 


1 Copy the DECW$BOOK and DECW$BOOKSHELF files produced by 
the online bookbuild to the online review directory. 


2 Check the text file LIBRARY. DECW$BOOKSHELF file to see whether 
there is already an entry for the book you have built. 


¢ If there is already an entry, proceed with step 3. 


¢ If there is not already an entry, append the book’s 
DECW$BOOKSHELF file to LIBRARY. DECW$BOOKSHELF. 
Use the command: 


$ APPEND xxxxPRO.DECWSBOOKSHELF LIBRARY .DECWSBOOKSHELF 
3 Run the DECwindows Bookreader. 


2.11.1 Running the DECwindows Bookreader Remotely 


As stated previously, DECwindows Bookreader performance improves 
greatly when it is run on a large memory system. If you have an account 
on a large memory system, you can run the Bookreader on that system, 
and direct its output to your workstation screen. The process by which you 
can do so varies, depending upon the setup and rules governing the use of 
the large system. Consult the system manager of the large system for the 
best means of running remote DECwindows processes on it. 


The following is the general procedure for running the Bookreader 
remotely. 


e Allow your large system account access to your workstation. From 
the DECwindows Session Manager on your workstation node, select 
the “Security” option of the “Customize” pull-down menu. Add various 
forms of your node name::username, such as HELENA::DRENCH 
and DIMOND::DRENCH. You cannot use a cluster alias; you use the 
wildcard *::username at your own risk, especially if your name is 
SMITH. 


© Use the following command procedure, or use something similar: 
$! X$BOOKREADER.COM 


§ BOOKLOG TEMP = FSTRNLNM("“DECWSBOOK", "LNMSPROCESS") 
$ DEFINE DECWSBOOK WORK1$: (DRENCH.ONLINE_BOOKS] 

$ IF Pl .EQS. "" 

$ THEN 

$ SET DISPLAY/CREATE/NODE=MYNODE:: !Use your nodename here 
$ SET PROC/NAME="BR_on_MYNODE" !Here too 

§ ELSE 

$ SET DISPLAY/CREATE/NODE®#’ p1’ 

$ SET DISPLAY/CREATE/NODE="BR_on_’’p1’" 

$ ENDIF 

$ MCR DECWSBOOKREADER 

§ DEFINE DECWSBOOK ‘BOOKLOG TEMP’ 
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¢ Define a symbol in your LOGIN.COM that you can later use to invoke 
the bookreader, such as: 


$ BOOKREAD :== @X$BOOKREADER 


e After you execute LOGIN.COM or define the symbol, you can run 
DECwindows remotely by entering the symbol name. 


Notes: There is a known problem where the bookreader will crash 
while it is painting the topic window and there is rapid mouse 
movement. This problem is noticed in accounts with *very* low 
ASTLM quota. The solution is to ask the large system manager to 
raise your ASTLM quota. 


You can also access the bookreader from a DECwindows 
FileView process running remotely on a large system. Running 
DECwindows FileView remotely is discussed in the DECwindows 
documentation. 


2.12 Checking Books Online 


This section explains what to look for when checking an online book. 
Writers and editors should check books on line at every major milestone 
for the book. For a hardcopy/online book, for example, you might check the 
online book at least at field test and final drafts, then do a follow-up check 
just before final production. Checking a book often can help you prevent 
last-minute problems. 


A thorough examination of an online book can take several hours, 
depending upon its size and the number of figures, tables, and examples it 
contains. 


Check a PostScript version of the book against the Bookreader version 
of the book. Make sure you can view the entire book on line, and note 
anything that looks incorrect in the online version. 


To scroll through an entire document, click on the Next Topic button, 
then use the scroll bars to scroll] to the end of each section. As you move 
the pointer over the text, hot spots show up as thin rectangles that outline 
text that can take you to another topic. For example, if there is a rectangle 
around “Table 1" and you click on that hot spot, Table 1 is displayed in a 
separate window. 


For more information about how to use the Bookreader, see the VMS 
DECwindows Desktop Applications Guide or Using the Bookreader. 


The following checklist summarizes things you can look for as you scroll 
through a document. 


1 Click on the bookshelf entry for the book. The contents page should 
appear in the main window and the title page should appear in the 
topic window. 

2 View the book sequentially in the topic window. To do this, you click 
on the “Next Topic” button and move the scroll bar, as required, to 
view each entire topic. While doing this, click on each hotspot (formal 
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table, formal figure, formal example, footnote, or popup window). A 
thin rectangular box indicates the location of a hotspot. 


You may find it helpful to approach the sequential search with a 
printed copy of the book, or, at least, a list of all formal figures, tables, 
or examples. The critical problem for which to check is a missing 
formal figure, table, or example. A formal figure, table, or example 
would not appear in a sequential search if there is not a <REFERENCE> 
tag in the book’s sources that points ‘to it. (It is of little help to a 
reader in the middle of a page that the “missing” formal figure, table, 
or example is listed in and accessible only from the table of contents.) 


Things to check for as you view the online book: 
¢ Can you page through the entire document? Is there missing text? 


¢ Do you have to perform an excessive amount of scrolling? If 
so, consider using the <SET_ONLINE_TOPIC> tag to change topic 
granularity as appropriate for your book (see Section 2.8.1). Topic 
length should not be too long (more than five to ten screens) or too 
short (less than % of a screen). 


e Are all informal figures, tables, examples (especially those with 
callouts) easy to view, or must you use the horizontal scroll bar to 
view them entirely? If so, consider using an online popup sequence 
(as discussed in Section 2.8.3) to cause the Bookreader to create 
& pop-up window for the troublesome informal figure, table, or 
example. 


¢ Does the topic window contain only the title of a chapter, appendix, 
or part? It’s likely that the head tag immediately follows the 
<CHAPTER>, <APPENDIX>, or <PART> tag. In this case, consider 
deleting the first <HEAD1> tag or adding an overview paragraph 
just after the chapter title. 


e Is each cross-reference a hotspot? If a cross-reference is not a 
hotspot, it has been hardcoded in the source file (for instance as 
“See Section 2.1.”) Use the <REFERENCE> tag in the source file to 
make the cross-reference “hot.” Does each “hot” cross-reference 
bring you to useful information? 


e Are the correct figures displayed? It’s very easy to mistype a figure 
file name. 


e Is the display attractive? Is there excessive white space? Is the 
formatting correct? (See Section 2.8.3 for some examples of SDML 
coding practices that produce unattractive online output.) 


Scroll through the table of contents. Can you access the entire table of 
contents? 


Access each topic by clicking on the corresponding table of contents 
entry. Access the preface and click on “Previous Topic” to page back to 
the Copyright Page and Title Page. Access each section and subsection. 
Access each table, figure, and example. 


§ Click on the “Index” button. Can you access the entire index? 
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Check that index entries take you to a spot relatively close to the 
information indexed. An index entry always takes you to the top of 
the topic where the <X> tag is located. Most of the time, the indexed 
information is within one or two screens and that is fine. Sometimes, 
though, you must click on “Next Topic” more than five times to find 
the information, or the information is in a separate topic completely. 
Consider moving the <X> tag so that it is closer to the information it is 
indexing. 


Click on the “Contents” button. Does the table of contents reappear? 
Check text that should be shown in second color. 


Any user input should show up in boldface type in the Bookreader. For 
the text to show in boldface type, writers must place the <u> tags in 
the same way as they mark second color in the hardcopy version of the 


After a thorough online check, be sure to do a follow-up check to verify 
all corrections. 


Exit the Bookreader. 


2.13 Delivering the Book to Graphic Services 


The requirements for submitting a book to Graphic Services depend on 
the type of production being done. The following sections describe the 
procedures for online/hardcopy and online-only production. 


2.13.1 Submitting a Book For Online/Hardcopy Production 


When the book has built successfully for hardcopy and online, the writer 
proceeds with the following steps: 


Checks the following files into the appropriate CMS library: 

— Profile 

— All elements 

— All include files 

— XREF file from successful build 

— MAP_LIS file from successful online bookbuild! 

— All UTOX art that was not generated by Graphic Services 
Submits the following items to the editor: 

— Hardcopy log files from the successful online and hardcopy builds 


— Hardcopy MAP_LIS files from the successful online and/or 
hardcopy build (VMS writers only)! 


— Hardcopy output from the hardcopy (PostScript) build 


1 Automatic document set building, as used in the VMS documentation group, requires the MAP _LIS file. 
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— Location where the output from the online build may be viewed 
(for editor’s pre-production check). 


¢ Notifies the editor that all files have been placed in the CMS library. 


2.13.2 Submitting a Book for Online-Only Production: 


2.13.2.1 


2.13.2.2 


Once you have built the book, including all art, successfully and are 
satisfied with its online display, you can deliver the book to your editor for 
online-only production. You can do this in one of two ways: 


¢ Submit the source files to Graphic Services, where they will be built, 
proofread, and prepared for transfer to the release engineer. (This is 
essentially the same procedure used for online/hardcopy production.) 


¢ Build the online book and submit the DECW$BOOK file to Graphic 
Services for proofreading. In this case, you are responsible for 
incorporating the proofreader’s comments, performing the final book 
build, and preparing the final online book files for transfer to the 
release engineer. 


The method you use depends on your group and its available resources. 
At the pre-production meeting (see Section 2.4,) you should identify the 
submission procedure that meets your requirements. 


Submitting Source Files for Online-Only Production 

If Graphic Services has agreed to build, proofread, and transfer the online 
books to the release engineer, the steps for submitting the book to GS are 
the same as those listed in Section 2.13.1. 


Submitting DECW$BOOK Files for Proofreading 

If Graphic Services is only responsible for checking and proofreading the 
online book, you are responsible for incorporating the proofreader’s queries 
and building the final DECW$BOOK file. 


To submit a book for proofreading, give your editor the following items: 
¢ Hardcopy of the book (PostScript version) or a detailed list of changes 
¢ A pointer to the final DECW$BOOK and DECW$BOOKSHELF files 


— Make sure that the file protection is set correctly to allow the 
editor to access the files. 


When Graphic Services completes the proofreading of your book, your 
editor or project leader will give you a list of proofreader’s comments. 
Discuss these comments with your editor and decide which would be 
worthwhile applying to the book’s source files. You should balance the 
advantage of making the change against the risk of introducing new 
and impenetrable errors into the SDML files. Currently, writers are 
encouraged to correct the following: 


¢ All hotspot problems (except in front matter) 


3 In the VMS group, the document set builder builds the final DECW$BOOK files, and the project leader 
notifies the release engineer when the books are ready. 
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e All problems with accessing tables, figures, and examples from text 
e All typos 


You should also check reported blank pages to ensure that text was not 
dropped or files miscoded during the online conversion process. 


Whatever you do, bear in mind that making any change involves again 
reserving files from the book’s CMS library and a repeat of step 2 in 
Section 2.13.2. It is better to postpone fixing a minor problem than to 
introduce a delay in final production. 


Once the proofreader’s changes have been dealt with, the writer again 
ensures that the book builds successfully and is viewable. The writer then 
replaces all reserved files in the book’s CMS library and notifies the editor. 
The editor notifies the project leader.® 


* In the VMS documentation group, once selected proofreader’s changes have been made and pertinent files 
replaced in CMS, the document set builder rebuilds the deliverable books and sends final output and library 
files to the release engineer. 
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Editors perform the same kinds of tasks for online books that they perform 
for hardcopy books. They review manuals during the writing process, and_ - 
they guide books through the production process. When working on books 
that will be published online, however, editors check the online version 

of the book and use several different production procedures. The same 
basic procedure should be followed regardless of how the manuals are 
distributed. Production procedures, wherever possible, should be the same 
regardless of how manuals are published. 


This chapter describes the following procedures editors use for online-only 
and online/hardcopy books: 


e Reviewing docplans 

e Converting, submitting, and checking art 

¢ Editing books for online production 

e Viewing and checking online books (See note below.) 

¢ Guiding books through online/hardcopy production 

The first section provides an overview of the editing procedures needed 


for the online-only and online/hardcopy processes. The remaining sections 
contain descriptions of these procedures and guidelines for using them. 


3.1 Overview of Editing Procedures 


This section lists the procedures editors use for each of the following types 
of production: 


¢ New and revised books published online-only 


¢ Maintenance books (books with minimal changes) published online- 
only 


¢ New and revised books published simultaneously as online and hard 
copy (online/hardcopy) 


3.1.1 New and Revised Online-Only Books 


For new and revised books published as online-only versions, an editor 
does the following: F 


e Reviews docplans 


¢ Coordinates conversion of hardcopy art to online art (if not already 
done) 


¢ Coordinates preparation of art packages 
e Edits hard copies 
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¢ Checks online version before final production (writer and editor) 


Note: This is not simply a pre-submission requirement, and should 
happen regularly by both the writer and editor. 


¢ Guides books through the online production process 


3.1.2 Maintenance Online-Only Books 


For maintenance books, (books with no technical changes) published 
online-only, an editor does the following: 


¢ Coordinates conversion of hardcopy art to online art (if not already 
done) 


e¢ Checks online versions before final production (writer and editor) 
© Guides books through the online production process 

¢ Negotiates proofreading as needed 

e Coordinates transfer of files to release engineer 


3.1.3. New and Revised Online/Hardcopy Books 


For new and revised books published simultaneously as online and 
hardcopy versions, an editor does the following: 


e Reviews docplans 

e Obtains an LPN, if necessary. 

e Coordinates preparation of art packages 

¢ Edits hard copies 

e Checks online versions before final production (writer and editor) 
¢ Guides books through the online/hardcopy production process! 


3.2 Reviewing Docplans 


When reviewing docplans, editors should make sure that the following 
production information is included in every docplan: 


e Is the book new, revised, or maintenance (no technical changes)? 
e¢ Will the manual be produced online-only or online/hardcopy? 


— If the manual is being produced online-only, how will the file be 
submitted to GS, see section Section 3.8. 


© Do the milestones include time for checking the online version of the 
book? 


¢ Is there online help that requires editing and proofreading support? 
i) 
1 For VMS, the document set builder delivers the files to the release engineer, and the project leader handles 
build/verification coordination. 
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e Art requirements (For example, will UTOX screens or RAGS figures be 
included? How much new and revised art is needed?) 


3.3 Pre-Production Meetings 


Before a document is submitted for any type of final production work, a 
pre-production meeting should be held to define the work required by GS. 
Depending on the scope of the submittal, attendance by representatives 
from involved groups will vary. A member from each of the following 
groups should attend: 


¢ Writing (either the writer or the documentation project leader) 
¢ Editing (either the editor or the editing project leader) 

e GS art 

e GS composition 

¢ GS proofreading 

e SSB product planning 

The work items that need to be discussed include the following: 


e §©List of books that will be submitted, including the title and LPN for 
each book. 


¢ The schedule for submittal of each book, including the date of 
submittal to GS and the date of submittal to SSB. 


¢ The type of production that will be required for each book (online 
Mardcopy, online-only, hardcopy only). 


¢ Page size estimate for each book. 


¢ Estimated number of new and revised art figures, and anticipated 
format (UTOX, RAGS). 


e For online-only books, the submittal process that will be used (submit 
DECW$BOOK and DECW$BOOKSHELF files, or submit source files). 


e For online-only books being submitted as DECW$BOOK and 
DECW$BOOKSHELF files, the naming conventions of the files must 
be identified. 


¢ For online-only books, the amount of hardcopy support needed by 
proofreaders must be identified (hardcopy print-out of book or list of 
changes). 


e The target OLD disc that the online versions of the books are 
scheduled for. 


e For online bookbuilds, the anticipated DOCUMENT version and 
baselevel version required. 


e The primary contact for each book being submitted. 
e Any other outstanding issues that need to be resolved. 
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3.4 Converting, Coordinating, and Checking Art 
This section describes editing procedures and guidelines for the following: 
¢ Converting hardcopy art to online art 
© Coordinating preparation of art packages for new and revised books 
¢ Checking art 


The art requirements for online books depend on the following: 
¢ Whether the book has been converted to the online doctype 
¢ Whether the book is new or revised 


If a book has not been converted to the online doctype, an editor works 
with the book’s writer and an artist to have the hardcopy art converted to 
online art. If a book is new or revised, an editor works with the writer 

to determine the art requirements for the book. (For example, will 
existing art need to be corrected or modified? Will any new art be created? 
Are overlays required for hardcopy art? What tools will be required to 
create the art?) The editor then coordinates with the Graphic Services 
art department, which prepares an art package for every book in final 
production. 


3.4.1 Converting Hardcopy Art to Online Art 


To convert existing hard copies of art to online art that can be used 

with the online doctype, an editor submits marked-up copies of existing 
hardcopy art to GS. An artist redraws the art using RAGS and places 
the finished art file in an art directory. After it is proofread/checked and 
the GS coordinator notifies the editor that the art is finished. The editor 
notifies the writer. The writer copies the appropriate figure files from this 
directory and uses them to build the online and hardcopy versions of a 
book. 


When hardcopy art needs to be converted to online art, an editor does the 
following: 


1 Requests the current art control list from GS. 


2 Reviews the art control list to determine the amount and type of art 
that needs to be converted. 


3 Meets with the appropriate Graphic Services art supervisor to discuss 
and schedule the art to be converted. 


4 Edits hard copies of art to conform to current art standards. 


§ Arranges for writer to copy drafts of art (generated with RAGS or 
UTOX) to DONVAN::ARTIN directory. Both Postscript and .BIN files 
should be saved. 


6 Submits marked-up art and art control list to Graphic Services with 
completed job requisition form. 


' For VMS, the copying of art figures is done automatically to CMS libraries. 
a4 


3.4.1.1 


Note: 


3.4.1.2 


3.4.1.3 


3.4.1.4 
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7 Writer and editor review/check art. 

8 Resubmits art for corrections if necessary. 

9 Requests copy of final art control list from GS. 
10 Gives the updated art control list to the writer. 
11 Checks art in online book. 


The following sections contain guidelines for the procedures that need 
more explanation. 


Requesting an Art Control List 

To request a copy of a current art control list, fill out a GS requisition form 
and request a copy of the book’s current art control list. Be sure to include 
the old and new LPNs. 


You will need copies of the figures in the book to mark up and submit for 
conversion. You can photocopy them from the latest version of the book, or 
you can request them from Graphic Services at this time. 


If you request hard copies of the figures from GS, be sure to check 
them against the figures in the latest version of the book to ensure 
that they are the most current versions. 


Reviewing an Art Control List 
When you have a copy of the current art control list, do the following: 


¢ Check the art list against the figures that were printed in the latest 
version of the book. 


© Make sure the list is current and that none of the art on the list is 
obsolete or has been deleted from the book. (By submitting copies 
of what appears in the book, you are sure to have the most current 
version. Any shading and last minute corrections will be included.) 


¢ Meet with the writer and verify that all of the figures on the list and 
in the book should be converted. 


Editing Hardcopy Art 
Before submitting art to Graphic Services for conversion, mark up hard 
copies of the art using the current CUP-ZK Production Art Guidelines. 


Submitting Marked-up Hardcopy Art 
To submit hardcopy art to Graphic Services for conversion, do the 
following: 


e ill out a Graphic Services requisition form for every book. 


© Submit the requisition form to Graphic Services with the following 
items: 


— Acopy of the art control list, indicating any obsolete figures 
— Marked-up copies of any revisions to existing art 


3.4 Converting, Coordinating, and Checking Art 


3.4.1.5 Checking Converted Art 
To check the converted art, refer to the guidelines in Section 3.4.4 


3.4.1.6 Resubmitting Art for Correction 
If art needs to be corrected, do the following: 


¢ Mark any corrections and changes clearly on the hardcopy of the 
converted art. 


Note: GS provides a hardcopy of the art that has been converted 
to online art. This is the copy that you should mark up and 
submit for corrections. 


e Fill out a new Graphic Services requisition form. 
¢ Submit the requisition form and the art corrections to GS. 


3.4.1.7 Giving Updated Art Control List to Writer 
When all of the art has been converted and corrected, request an updated 
art control list from GS. 


Give the updated art control list to the writer; the writer inserts all of the 
pica measurements into the figure file tags in the source files. 


3.4.1.8 Checking Art On Line 
After the writer has built an online version of the book that includes art, 
the editor and writer checks the art. 


3.4.2 Coordinating Art Packages for Revised Books 


To coordinate the preparation of art packages for revised books that will 
be published as online-only or online/hardcopy versions, an editor does the 
following for every book: 


1 Requests an art control list immediately upon receiving an assignment. 


2 Reviews the art control list with the writer and determines which art 
needs to be converted, revised, or created. 


3 Arranges for writer to copy drafts of art (generated with RAGS or 
UTOX) to DONVAN::ARTIN directory. 


4 Submits marked-up art and art control list to Graphic Services with 
completed job requisition form. 


Checks completed art. 

Resubmits art for corrections if necessary. 

Requests updated art control list when all art corrections are complete. 
Gives writer updated art control list. 

Checks online version during preproduction verification. Examines 
specific details, including cropping, placement, sizing, and black lines. 


The following sections contain guidelines for procedures that need more 
explanation. 
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3.4.2.1 


3.4.2.2 


3.4.2.3 


Note: 


3.4 Converting, Coordinating, and Checking Art 


Requesting an Art Control List 

To request a copy of a current art control list, fill out a GS requisition form 
and request a copy of the book’s current art control list. Be sure to include 
the old and new LPNs. 


You will need copies of the figures in the book to mark up and submit for 
revision. You can photocopy them from the latest version of the book, or 
you can request them from Graphic Services at this time. 


If you request hard copies of the figures from GS, be sure to check 
them against the figures in the latest version of the book to ensure 
that they are the most current versions. 


Reviewing an Art Control List 
When you have a copy of the current art control list, do the following: 


° Check the art list against the figures that were used in the latest 
version of the book. 


¢ Make sure the list is current and that none of the art on the list is 
obsolete or has been deleted from the book. 


¢ Meet with the writer and verify that all of the figures on the list and 
in the book will be included and find out how much new art is needed. 


Submitting New and Revised Art to GS 

All requests for new and revised art must be submitted to Graphic Services 
at least six weeks before the book’s final production date. An art package 
must be complete two weeks before a book’s final production date. Discuss 
individual book deadlines with the appropriate GS art supervisor. 


Work closely with the writer and submit art as soon as the technical 
information is firm. All corrections do not have to be submitted at one 
time. Submitting art in stages as soon as it is firm reduces the chances 
of a “bottleneck” in Graphic Services or a mad rush before the final 
production date. This is especially important for books that have many 
figures. 


For new art, writers can 
¢ Give editors hand-drawn rough sketches 


e Create online art drafts using RAGS and copy the files to the 
DONVAN::ARTIN directory. (RAGS files are considered art and will be 
assigned art control (ZK) numbers.) 


e Capture screen displays using UTOX and include them in their source 
files. (UTOX files are not considered art and are not assigned ZK 
numbers.) 


¢ UTOX annotated images are assigned ZK numbers, and stored in 
CMSART. 


To submit RAGS or UTOX files to GS, an editor must: 


¢ List the RAGS or UTOX file names on a Graphic Services requisition 
form 
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e Attach copies of the figures or screens (and any changes) to the GS 
requisition form 

To submit new and revised art to GS, an editor must: 

e Fill out a Graphic Services requisition form for every book. 

¢ Submit the requisition form to Graphic Services with the following 
items: 
— Acopy of the art control list, indicating any obsolete figures 
— Marked-up copies of any revisions to existing art 
— File names of UTOX files with captions or RAGS files 


3.4.2.4 Checking Revised Art 
To check revised art, refer to the guidelines in Section 3.4.4 


3.4.2.5 Resubmitting Art for Correction 
If art needs to be corrected, do the following: 


¢ Mark any corrections and changes clearly on the hardcopy of the 
revised art. 


Note: GS provides a hardcopy of the art that has been converted 
to online art. This is the copy that you should mark up and 
submit for corrections. 


¢ Fill out a new Graphic Services requisition form. 
e Submit the requisition form and the art corrections to GS. 


3.4.2.6 Giving Updated Art Control List to Writer 
When all of the art has been converted and corrected, request an updated 
art control list from GS. 


Give the updated art control list to the writer; the writer inserts all of the 
pica measurements into the figure file tags in the book. 


3.4.2.7 Checking Art On Line 
After the writer has built an online version of the book that includes art, 
use the guidelines to check the art. 


3.4.3 Coordinating Art Packages for New Books 


New books require special art considerations and are handled by GS on 
an individual basis. To coordinate the preparation of the art package for a 
new book, an editor does the following: 


1 Meets with the appropriate Graphic Services art supervisor to discuss 
the stability of the art and the amount of art that will be needed. 

2 Works with the writer to find out whether any existing art can be 
used. 


3 Submits hardcopy rough sketches and filenames of RAGS and UTOX 
draft files created by writers to GS. Can request GS to proofread art 
changes. 
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_ Checks art (writer and editor). 


Resubmits art for correction if necessary. 
Requests final art control list from GS. 
Gives final art control list to writer. . 


Checks figure placement in online version during a preproduction 
online check. 


3.4.4 Checks Completed Art 
When checking the completed art, an editor uses the following guidelines: 


Check the marked-up hard copy you submitted against the hardcopy of 
the online art you receive from GS. 


Make sure that the new version matches the marked-up copy you 
submitted and that no errors were introduced. 


Double-check the pica measurements that appear on the slug line 
(the banner at the top of the figure) of every figure against the pica 
measurements on the art control list. 


The art control list has two columns for pica measurements: 
— The HC_PI column contains the PostScript measurement.! 
— The GE_PI column contains the online measurement. 


The slug-line measurement includes the scaled size for reduced art and 
should be the same as the measurement listed in the HC_PI column 
on the art control list. 


Look for anything that doesn’t look quite “right”. For example, the 
following table lists some of the problems and solutions encountered 
during the conversion of the art in the VMS docset. 


Table 3-1 Art Problems and Solutions 


Problem 


Solution 


Some of the arrowheads appear off-center Editor must resubmit art for correction. (The artist has to adjust 


when an arrow is curved. 


the angle of the curve very carefully until the arrowhead appears 
correct.) 


Type size is too small in hardcopy version. Artists check size of type on reduced art. If the type size is less 


than 6 points., the artist notifies the appropriate editor. The editor, 
writer, and artist must work out a solution. For example, some 
figures can be redesigned or made into two figures. 


Callout type size is too small in reduced art. Editor, writer, and artist must redesign the figure so the callouts can 


be made larger. 


(continued on next page) 


1 How to convert for LNO3 copy— to get the SIXEL file measurement, multiply the postscript measurement 


by 1.08% 
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Table 3-1 (Cont.) Art Problems and Solutions 


Problem 


Solution 


Hardcopy art is too large to fit on one page 
but Is one piece on line. (For example, large 
keyboards be 100% on line because the 
reader can use the scroll bar to view them, 
but they are illegible when reduced to fit on 
one hardcopy page.) 

How to indicate second color in online art. 


How to indicate shaded areas in online 
keypad diagrams. For hard copy versions, 
writers use the <keypad> tag to create 
keypads. Because an artist uses overlays 
to highlight various functions, the highlighted 
areas are not shown in the online doctype. 
How to indicate shaded areas in online code 
examples. (For example, highlighting the 
buffer line or cursor movement.) Artists use 
overlays for hardcopy versions. 

How to size art that is shared by different 
doctypes. 


The art has to be pasted up for hardcopy. The editor must let the 
Graphic Services compositian supervisor (Nance Leaver) know 

of any special requirements ‘before the book is submitted for final 
production. For example, if a large keyboard is divided into two 
figures that must be pasted up on facing pages. CUP Engineering 
is aware of the problem 


Artist uses monospaced type to indicate second color. Note that 
the type is not boldface. 


Artist redraws every keypad with RAGS and assigns a ZK number 
to each figure. The ZK number does not appear in figure. The 
artist has to crop it out. 


A solution is still under discussion. 


Currently, artists size figures to the smaller doctype. 


Editing Manuals for Online Publication 


An editor edits online manuals during the writing process whenever a 
writer distributes review drafts. When editors view and check online 
books, they are checking to make sure books are viewable, complete, and 
formatted correctly. 


Editors make editorial comments on hard copies of a draft; they do not 
make corrections in source files. Sometimes a content-related issue “jumps 
off the screen” when an editor is checking an online book. The editor 
should note such an item on a hard copy of the book and give it to the 


writer. 


For more information about preparing to view an online book, see 


Section 2.11 


Checking Books On Line 


This section explains what to look for when checking an online book. 
Writers and editors should check books on line at every major milestone 
for the book. For a hardcopy/online book, for example, you might check the 
online book at least at field test and final drafts, then do a follow-up check 
just before final production. Editors should also do a follow-up check just 
before the book is ready to be included on the CD. Checking a book often 
can help you prevent last-minute problems. 


For information about how to use the Bookreader, see the VMS 
DECwindows Applications Guide and Using the Bookreader. 


3.6 Checking Books On Line 


Check a PostScript version of the book against the Bookreader version 
of the book. Make sure you can view the entire book on line, and note 
anything that looks incorrect in the online version. 


To scroll through an entire document, click on the Next Topic button, 
then use the scroll bars to scroll] to the end of each section. As you move 
the pointer over the text, hot spots show up as thin rectangles that outline 
text that can take you to another topic. For example, if there is a rectangle 
around "Table 1" and you click on that hot spot, Table 1 is displayed in a 
separate window. 


The following checklist summarizes things you can look for as you scroll 
through a document. 


1 Scroll through the TOC. 


Look for missing information, accuracy of the TOC, section numbers 
overwriting other text (this can happen with a 5-digit section number), 
and duplicate section numbers. If symbolic names used for references 
are identical in two places, this will mix up the order of the numbers in 
the online version, even though it might not show up in the hardcopy 
version. 


2 Check the front matter for the correct information: 
¢ Copyright date 
e Revision/Update information 
¢ Software Version 
¢ Order number 
e Current trademark information 


Make sure the DOCUMENT statement does not overwrite the 
trademarks. 


e Correct conventions page 


Also make sure the following sentence is added to the user input 
convention: "For online versions, user input is shown in bold." 
Note that the word bold is shown in boldface type. 


3 Spot check the index. 
e Look up two entries for each letter represented in the index. 


Make sure you don't need to scroll through more than two screens 
before you find the information. 


e Make sure that the index is complete. 


¢ Recommended: Make sure index entries are not coded within a 
formal figure, table, or example. If a reader clicks on an index 
entry resulting from this type of coding, the Bookreader displays 
the pop-up window alone. Without additional context, such entries 
usually are not helpful for a reader. 


4 Check for consistent and appropriate length of topics. 
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This is called granularity. Topics should not be too short (less than 
one quarter screen) or too long (more than five screens, as a guideline). 
The default granularity is usually sufficient; however, writers can 

use the <SET_ONLINE_TOPIC> tag to change the granularity. For more 
information about granularity, see the Coding Documentation Source 
Files for the DECwindows Bookreader. 


Check for blank topics. 


Make sure text follows each heading. For example, if Section 1.1.1 
immediately follows Section 1.1, the topic for Section 1.1 will be blank 
except for the heading. 


Check all cross-references and references to formal! tables, figures, and 
examples. 


¢ Make sure every formal figure, table, and example has a 
corresponding reference in text. Every reference should be a 
hot spot. 


¢ All cross-references should be hot spots. Cross-references for which 
the <REFERENCE> tag is not used will not be hot spots. Check the 
Preface closely for this. 


° Make sure that there is always a direct way for the user to get to 
each section, figure, table, or example from the text. 


For example, do not write, "See Sections 1 through 3." no direct 
way for the user to get to Section 2 in this case. Instead, specify 
what information users can expect to find in each section. 


¢ Hot spots should span the name of the entire reference. 
For example: 


Section 3.1, Example 1, Table 3-4 should be hot spots, not just the 
numbers 3.1, 1, or 3-4. 


Check all formal figures and tables. 
¢ Make sure table columns do not overwrite. 


This can happen with long names that require underscores or 
dollar signs. 


e Make sure the correct figures are displayed. 


Do not assume that the figures are correct because they are correct 
in the hardcopy version of the book; it is very easy to mistype a 
figure file name. In addition, some art problems are specific to the 
online version. 

© Make sure online figures do not contain black spots outside of the 
image area. 

Check all informal figures, tables, and examples. 


Because these items cannot be accessed through the TOC or index, you 
must scroll through the text to see them. If you must scroll to see an 
entire figure, table, or example, the writer should consider using the 
<ONLINE_POPUP> tag to make the figure, table, or example pop up in a 
separate window. 


3.6 Checking Books On Line 


9 Check text that should be shown in second color. 


Any user input should show up in boldface type in the Bookreader. For 
the text to show in boldface type, writers must place the <U> tags in 
the same way as they mark second color in the hardcopy version of the 
book. 


10 Also, for layered products, any extensions to ANSI standards should 
show up on line in a shaded area. _ 


11. After a thorough online check, be sure to do a follow-up check to verify 
all corrections. 


3.7 Guiding Books Through Online/Hardcopy Production 


The procedures used to produce online/hardcopy books are similar to the 
traditional hardcopy production path through Graphic Services, except for 
the following: 


¢ To accommodate integrated graphics, PostScript output is used for 
hardcopy; and, the VT600 is used for the repro-generating device. 


¢ Operators perform an online bookbuild after the VT600 hardcopy is 
generated. 


¢ Proofreaders and editors check online bookbuilds. 


This section contains guidelines for the following procedures an editor uses 
when guiding a book through the online/hardcopy production process: 


¢ Getting a book ready for final production 
¢ Submitting jobs to GS 

© Checking PostScript drafts 

e Checking VT600 repro 

e Checking online books in final production 
¢ Preparing repro packages 


For an overview of the complete online/hardcopy production process, 
refer to the online/hardcopy flowchart in Chapter 1. For descriptions of 
the online/hardcopy procedures Graphic Services personnel use, refer to 
Chapter 4. 


3.7.1 Getting a Book Ready for Final Production 
Before submitting a book for final production, do the following: 


1 Submit print-spec information to print coordinator four to six weeks 
before the to-print date. 


2 Ensure that the online submission form has been submitted to the 
release engineer eight to ten weeks prior to the consolidation date. 
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3 Check with writer and ensure that writer’s CMS, or CMSDOC account 
is current and the writer has access to the appropriate CMS library. 


3.7.2. Submitting a Book to GS 
To submit a book to Graphic Services for final production, do the following: 


1. Check CMS library (after being notified by writer) to make sure SDML ~ 


files have been checked in and are unreserved. The following files 
should be checked into the appropriate CMS library: 


¢ Profile 

e All elements 

e All include files 

e XREF files 

° MAP LIS file from successful online bookbuild! 


e All UTOX art that was not generated by Graphic Services. 
(Writers do not create CMS elements for artwork that has been 
generated by Graphic Services.) 


e Arrange to get art not created by GS, to GS 


2 Perform a production editing pass on the latest PostScript draft. 
Check the latest version of the online book. 


3 Give the following items to the Graphic Services coordinator by 3 p.m. 
on the day of final production submission: 


¢ Completed Graphic Services Job Requisition Form, which requests 
Graphic Services to clean up files, generate first PostScript draft, 
and proofread. 


Note: Be sure to write any special instructions or processing 
information on the requisition form. For example, if you 
have art files not created by GS, include the full file names 
on the requisition form and check that the file protection 
permits world access. 


¢ Updated art control list 


¢ Hard copies from writer (PostScript draft of book, LOG file from 
online bookbuild, and LOG file from hardcopy bookbuild) 


3.7.3 Checking a First PostScript Draft 
To check a first PostScript draft, do the following: 


1 Resolve all queries from the proofreader and check first PostScript 
draft for bad line and page breaks. 


Note: The online doctype ignores hardcopy line and page break tags. 


1 Automatic document set building, as used in the VMS documentation group, requires the MAP LIS file. 
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2 Make no additional editorial changes at this time, unless the changes 
are technical corrections. 


3 Return the first PostScript draft to the Graphic Services coordinator 
with a new Graphic Services requisition form that requests the 
following: : 

e a hardcopy bookbuild 
¢ second PostScript draft 
¢ an online bookbuild 


¢ proofreading 


3.7.4 Checking a Second PostScript draft | 
To check a second PostScript draft, do the following: 


1 Review second PostScript draft to verify page and line breaks and to 
confirm that other corrections have been included. 


2 Resolve all proofreader’s queries. 


Return the second PostScript draft and a new Graphic Services 


requisition form to Graphic Services coordinator that requests the 
following: 


e a VT600 copy 

¢ sending VT600 repro to art 

¢ an online bookbuild and a duplicate PostScript draft 
¢ proofreading 


3.7.5 Checking a VT600 Copy 
To check a VT600 copy, do the following: 
1 Check any corrections made by artist. 


2 Give final PostScript draft to writer, so the writer can mark it for ' 
second color. 


Note: User input appears in the online doctype in boldface type. 
Extensions to ANSI standards will appear shaded. 


3 Check repro for missing pages or type and correct folios. 


3.7.6 Checking an Online Book 
If the proofreader finds problems with the online manual or has questions, 


the proofreader sends questions to the editor. The editor does the 
following: 
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1 Redefine the logical name DECW$BOOK to point to the directories 
REDINK::REDINK$DUA2:[(0OLDPRO.mmmCD]. ! 


$ define decw$book redink::redink$dua2: [olprod. jancd] 
2 Resolve proofreader queries 
3 Spot check any areas you know may have problems 


4 If corrections are needed, mark them on the duplicate postscript 
draft, put paper clips on the marked pages and submit to GS (with a 
filled-out requisition form) for correction. 


3.7.7 Preparing a Repro Package 
To prepare a repro package for submission to the SSB, do the following: 
1 Create assembly sheet. 
2 Fill out repro checklist. 


3 Bring complete repro package to Graphic Services print coordinator 
by 3 p.m. the afternoon before the SSB submission date (that is, the 
to-print date). The complete repro package consists of the following: 


e WVT600 copy 

¢ second color mark-up 

¢ cover and spine mechanicals 

¢ layout board (which must contain the part number) 
¢ assembly sheet 

¢ repro checklist 

¢ copy of final print spec 


The Graphic Services print coordinator adds the final print spec to 
the repro package after verifying the information with the editor. 


3.7.8 Submitting CDROM Files 


The editor or person responsible for submitting the book to Graphic 
Services should do the following: 


1 Check that the operator has made the final DECW$BOOK file 
available in the [OLPROD.mmmCD)] subdirectory. 
2 Rename the file with the correct 2-5-2 or 2-5-2-4 number.” 


3 Verify that the bookshelf files include each book in the documentation 
set. 


1 If you have trouble accessing the file, copy the readable output to your directory (from the online bookbuild) 
that is located in the directory REDINK::REDINK$DUA2:OLPROD.mmmCD] to your directory. 
For example, for the January CD, the directory is [OLPROD.JANCD]. 


* For VMS, the project leader delivers books on backup tape to the release engineer already renamed. 
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4 Notify Release Engineer that the files are ready. 


3.8 Guiding Books Through Online-Only Production 


The procedures used to produce online-only books are similar to the 
traditional hardcopy production path through Graphic Services; however, 
online-only production can be done in one of two ways: 


¢ Following the path used for hardcopy production, the source files for 
an online book can be submitted to Graphic Services, where they will 
be built, proofread, and prepared for transfer to the release engineer. 


¢ Using a slightly different approach, a writer can build the online 
book and submit the DECW$BOOK file to Graphic Services for 
proofreading. In this case, the writer is responsible for incorporating 
the proofreader’s comments, performing the final book build, and 
preparing the final online book files for transfer to the release engineer. 


The first method is appropriate for groups that require the hardware 
and staffing resources in Graphic Services to do the final bookbuild 

and proofreading pass. The second method is more suitable for groups 
that have the necessary bookbuilding resources and would prefer to 
retain control of their source files. For example, the writing group might 
maintain its own CMS libraries for source control to maintain multiple 
versions of the documentation set. 


Prior to submitting the book to Graphic Services, the online-only 
procedures are the same as the online/hardcopy procedures for producing 
a book. The writer and editor should check the online version prior to 
submission. 


3.8.1 Submitting Source Files for Online-Only Production 


The procedure for submitting source files for online-only production is the 
same as the procedure described in Section 3.7, except for what you specify 
on the requisition form. For online-only production, request Graphic 
Services to build the book for online-only production and proofread. 


Resolve proofreader’s queries in the same manner as you would for 
hardcopy/online production. You might need to view the online version 
to answer some of the queries. 


If corrections are needed, mark them on the hard copy, put paper clips on 
the marked pages, and submit a new requisition form to GS for correction. 


Refer to Section 3.7.8 for instructions for submitting a CDROM package. 


3.8.2 Submitting DECWS$BOOK Files for Proofreading 


The second method for producing online-only books requires Graphic 
Services only to check the online version and to proofread new and 
changed portions of the document. The writer is responsible for 


incorporating any final changes into the source files and rebuilding the 
book. 
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Note: 


Copy the DECW$BOOK file and the DECW$BOOKSHELF file 
created by the build to [OLPROD.mmmCD)]. Make sure that the 
file name of the DECW$BOOK file corresponds to the entry in 
the DECW$BOOKSHELF file. For example, if the file name is 
4753pro.DECW$BOOK, the entry in the DECW$BOOKSHELF file 
created by the build should look like this: 


BOOK\ 4753PRO\Guide to Saving Trees 


The names of the DECW$BOOK and DECW$BOOKSHELF files 
must be identical. 


Give the following items to the Graphic Services coordinator by 3 p.m. 
on the day scheduled for submittal: 


¢ Completed Graphic Services Requisition form, which requests 
Graphic Services to proofread the online version. Make sure you 
specify the names of the DECW$BOOK and DECW$BOOKSHELF 
files on the Requisition Form. 


¢ Hardcopy version of the book (PostScript version). For online-only 
revisions the writer should mark change bars on the hard copy. 
For books with only minimal changes, a detailed list of changes 
might be appropriate if arrangements are made beforehand. 


Resolve proofreader’s queries in the same manner as you would for 
hardcopy/online production. You might need to view the online version 
to answer some of the queries. 


Give the proofreader’s queries to the writer, who incorporates the final 
changes and rebuilds the book. 


4 Graphic Services Production Procedures 


This chapter describes the procedures that operators, artists, and 
proofreaders use to produce online-only and online/hardcopy books. 


4.1 Online/Hardcopy Procedures 


The following sections describe the final production procedures GS uses 
to produce online and hardcopy versions of books from the same (SDML) 
source files. 


4.1.1 GS Coordinator Reserves Files 


When a book is submitted for final production, check with the writer 

to confirm file transfer arrangements for final production. For example, 
some groups use CMS or CMSDOC, others provide a tape of writers files to 
production, and others copy the stable files to an account on the production 
system. 


1 
2 


GS coordinator reserves the SDML files from CMS or CMSDOC. 


GS coordinator gives hard copies and job requisition form to 
composition supervisor. 


Composition supervisor assigns a Graphic Services operator to the 
book. 


Note: When a book is assigned to a Graphic Services operator, 
proofreader, or artist, that person is responsible for the book 
throughout the entire production process. 


4.1.2 GS Operator Cleans Up Files and Generates First PostScript Draft 


To clean up SDML files and generate a first PostScript draft, a Graphic 
Services operator does the following: 


1 


Copies .SDML files, XREF file, and any symbols files from the 
{finalpro] area. 


Checks elements against profile to make sure all elements are 
available. 


Copies figure files from DONVAN::ARTOUT.. 


Runs ONLINE_CLEANUP.COM! against the profile. This command 
procedure looks at every element in the profile. It checks for misplaced 
<p> tags and adds symbolic names to head tags. 


1 As of this writing, neither version of ONLINE_CLEANUP.COM have been verified to work with Version 2.0 
of the DECwindows Bookreader. 
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Checks ZK numbers and figure sizes in source files against the final 
art control list and corrects sizes if necessary. 


When cleanup is complete, a Graphic Services operator processes files 
individually by chapters, excluding TOC, and index, and produces the 
first PostScript draft. (In other words; the operator does not build the 
book.) | 


Submits first PostScript draft to proofreading supervisor. Proofreading 
supervisor assigns a proofreader to the book. 


4.1.3 Proofreader Checks First PostScript draft 
To proofread a first PostScript draft, a proofreader does the following: 


1 


Compares the PostScript draft word-for-word against the writer's hard 
copy and checks for the following: 


e Typos 

¢ Format incensistency 

¢ Bad line and page breaks 
¢ Spacing problems 

e Art placement problems 


e Anything that differs from the writer’s hard copy submitted to GS 
by the editor 


Returns writer’s hard copy and first PostScript draft to the Graphic 
Services coordinator. 


The Graphic Services coordinator then notifies the editor that the first 
PostScript draft is ready for review. (If the request date on the Graphic 
Services Job Requisition Form is in jeopardy, a member of GS personnel 
will notify the editor.) 


4.1.4 GS Operator Builds Book for Hardcopy and Online Version and 
Generates Second PostScript draft 


To build the book and generate a second PostScript draft, a Graphic 
Services operator does the following: 
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Makes all changes (as resolved by editor) in the source files. 


Adds appropriate final cleanup tags (line_break or page_break tags). 
(These tags are included in the SDML files but are recognized only by 
the hardcopy doctype.) 

Builds book for hardcopy version and generates second PostScript 
draft. This copy includes the TOC, index, and Reader's Comments 
pages (also “How to Order” page if it becomes a separate element). 


Builds book for online and performs online spot check of figures, tables, 
and examples. 


Makes corrections to source files and rebuild if necessary. 


Graphic Services Production Procedures 
4.1 Online/Hardcopy Procedures 


Returns job to assigned proofreader. 


4.1.5 Proofreader Checks Second PostScript draft 


When checking a second PostScript draft, a proofreader checks the 
following: 


1 
2 
3 


All changes, including line and page breaks, are verified. 
TOC matches the book. 
Index is completely proofed for typos and spot-checked for accuracy. 


When the proofreader returns first and second PostScript drafts to the 
Graphic Services coordinator, the Graphic Services coordinator notifies the 
editor that the second PostScript draft is ready for review. 


4.1.46 GS Operator Generates VT600 Repro and Builds Book for Online 


Version 


” 


To generate a VT600 copy and build the online book, a Graphic Services 
operator does the following: 


1 


Note: 


Incorporates into the source files final corrections received from the 
proofreader and editor. 


If there are more than a few minor changes, the operator 
should contact the editor when the changes have been made. 
The editor must check these changes as quickly as possible in 
the operator’s office. 


Builds book for the hardcopy version to incorporate any corrections 
and generates one VT600 repro for each book and two copies of final 
PostScript draft. 


Builds book for the online version, using the lastest version of tools, 
and views the online version to ensure it is intact. 


Copies the readable output file from the online 
bookbuild to the appropriate subdirectory 
REDINK: :REDINK$DUA2:[(OLPROD.mmmCD)]. 


Gives one final PostScript draft and VT600 repro to the assigned artist 
and gives the duplicate PostScript draft to the proofreader. 


4.1.7 Artist Pastes Up VT600 Repro | 
To paste up a VT600 repro, an artist does the following: 


1 


2 
3 


Pastes up on boards any pages that do not have folios (for example, 
front matter, part pages, Reader’s Comments pages, etc.). 


Manually moves text and art that cannot be done within source code. 


Brings completed VT600 repro and final PostScript draft to the 
assigned proofreader. 


4.1 Online/Hardcopy Procedures 


4.1.8 Proofreader Checks VT600 Repro and Online Version 
To proofread a VT600 repro, a proofreader does the following: 


1. Checks the final PostScript draft (which matches the VT600 repro) to 
ensure that type and art corrections have been made from the second 
PostScript draft. 


2 Photocopies any VT600 pages modified by a Graphic Services artist. 
3 Inserts photocopied pages into the final PostScript draft. 
4 Checks to see that the final PostScript draft matches exactly the 


VT600 repro (except for the "DRAFT" identifier, which is not on the 
VT600 pages.) 


§ Puts the VT600 repro in the Graphic Services repro cabinet. 


Note: VT600 repro must remain in Graphic Services. 


6 Returns final PostScript draft, which includes inserted photocopied 
pages, to the Graphic Services coordinator. This final PostScript draft 
is used as the second color mark-up copy. 


7 Checks the online version after the hardcopy version has been checked 
(and corrected, if necessary). 


To check an online book, a proofreader: 


— Runs the Book Verification Utility and uses the log file to record 
comments. 


— Opens the readable output file (from the online 
bookbuild) that is located in the appropriate subdirectory 
REDINK::REDINK$DUA2:(OLPROD.mmmCD]. 


¢ Ensures that the readable output file is complete. Clicks on all 
book elements (chapters, TOC, index) to make sure they are 
included. 


e Makes sure that every formal figure and table is included by 
clicking on each figure and table. 


e¢ Spot checks index entries to make sure the entries point to the 
correct topics. 

e §Skims the online version for “anything strange" like floating 
hyphens or symbols. (These problems are probably software 
bugs and should be reported to the CD release engineer as well 
as the editor. (The CD release engineer reports software bugs 
to CUP Engineering.) 

8 Proofreader annotates the Book Verification Utility! log file 
(ANALYSIS) and mails it to the editor. 


At the end of the online check, the proofreader notifies the GS coordinator 
that the online check is complete. 


1 As of this writing, the Book Verification Utility has not been verified to work with books built for Version 
2.0 of the DECwindows Bookreader. 
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The GS coordinator notifies the editor that the job is complete. 


4.1.9 GS Operator Builds Final Book for Online Version 


To build the final version of the online book, a Graphic Services operator ! 
does the following: 


¢ Incorporates into the source files final corrections received from the 
proofreader and editor. 


Note: If there are more than a few minor changes, the operator 
should contact the editor when the changes have been made. 
The editor must check these changes as quickly as possible in 
the operator’s office. 


¢ Builds book for the online version and views to be sure book is intact. 


e Copies the readable output file from the online 
bookbuild to the appropriate subdirectory 
REDINK::REDINK$DUA2:[OLPROD.mmmCD]. 


¢ Notifies the editor, proofreader, and Release Engineer that the book is 
ready for submission. 


¢ Notifies GS coordinator that files have been completed and transfered. 


4.1.10 GS Coordinator Notifies Editor 


When the hard copy and online versions are completed, the GS coordinator 
notifies the editor that files are ready for renaming and submission. 


4.1.11 Proofreader Checks Assembly Sheet 


After the editor prepares the repro package, the GS print coordinator 
brings the repro, second color mark-up, and assembly sheet to the 
proofreading supervisor. 


The proofreading supervisor gives these items to a proofreader who does 
the following: 


e Checks the assembly sheet against the repro and second color mark- 
up. 

¢ Returns repro, assembly sheet, and second color mark-up to the 
Graphic Services print coordinator. 


The Graphic Services print coordinator notifies the editor immediately if 
errors are found. 


1 VMS does its own final build. 


4.1.12 
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GS Print Coordinator Creates Final Print Spec 


To create a final print spec, a Graphic Services print coordinator does the 
following: 


¢ Resolves any problems with the editor and checks the repro package 
against the Repro Checklist. 


¢ Creates the final print spec and mails a copy to the editor. 


GS Print Coordinator Submits Book to SSB 


When the print spec is final, a Graphic Services print coordinator sends 
the repro package to Print Purchasing at the SSB. 


5 Online Project Leader 


The online project leader is one who is responsible for ensuring the online 
production cycle for the book(s) are in place and follows the book(s) 
through each process. The online project leader may be the supervisor, 
writer, or editor in the group. 

A documentation group decides which books will be included on a specific 
compact disc (targeted disc). According to the current schedule, an online 
CD release ships every two months, usually on the first Monday of the 
month. Preparing to ship a book or set of books on a given CD requires 
careful planning, scheduling, and coordination to ensure that books are 
ready on time. 


It is critical that someone coordinate art conversion and online 
proofreading long before the targeted disc ships. 


If a documentation group is to ship many books on a targeted disc, it 

is appropriate that a online project leader be assigned to coordinate the 
work delivered to Graphic Services and the files delivered to the release 
engineer. If only a few books are destined for a targeted disc, then it is 
appropriate that the editor and writer of each book coordinate to perform 
the steps outlined in this chapter. 


The online project leader for an online document project performs the 
following tasks: 


¢ Determines which online books must be provided on a targeted disc 


e Establishes a schedule specifying dates for the delivery of each book to 
Graphic Services and to the release engineer 


¢ Organizes the books in the online document set into a bookshelf 
(or bookshelves) such that they are easily accessible from the 
DECwindows Bookreader 


e Fills out the online submission form 


¢ Coordinates required work (for instance, online cleanup and other 
coding conventions) among the responsible writers, editors, product 
managers, and release engineer 


© Delivers final output files of all books to the release engineer 
The following sections describe each task in detail. 


5.1 Determining Online Books to Be Provided for a Targeted Disc 


The online project leader consults with writing management to determine 
which online books must be provided for a targeted disc. There are two 
requirements: 


¢ The online document set must support the software being shipped in 
the same software CDROM. 
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5.1 Determining Online Books to Be Provided for a Targeted Disc 


¢ In most cases, the online document set must be complete. If one 
or more books in the document set cannot be provided, the entire 
document set must wait until all books are ready. 


In general, the following documentation types do not ship in bookreader 
format: 


¢ Hardware installation and operation guides. 


¢ Master indexes. (Online bookbuilding software does not yet support 
the generation of master indexes. When master indexes are supported, 
they should be included in the online documentation set.) 


e Software product descriptions (SPDs). 
© Cover letters.! 
¢ CD booklets.! 


It may be required that certain .TXT files are required for CONDIST. 
The files need to be supplied in an online form, not bookreader. For 
example: 


— Release Notes 

- Installation Guides 
— Cover Letter 

~- Customer Letter 


The online project leader at this time creates a list of books that compose 
the online document set. This list must include the LPN, title, and order 
number of each book. This information will be useful in constructing 
bookshelves (see Section 5.3) and completing the online submission form 
(see Section 5.4). 2 The online project leader can add information to 

the list, such as art conversion or proofreading status, as the project 
progresses. 


5.2 Scheduling the Project 


The online project leader is responsible for establishing milestones for 
the delivery of the online document set. Generally, documentation 
milestones are derived from the shipping date of the targeted disc and 
are heavily influenced by the milestone dates set by the release engineer 
for coordinating the delivery of the entire contents of that CD. 


When scheduling milestones for the online document set, the online project 

leader must bear in mind the following requirements: 

1 Eight to ten weeks prior to the targeted disc date, the online project 
leader completes the online submission form and submits it to the 


release engineer. (For example, if the product is targeted for the March 
6 disc, the online submission form is due to the Release Engineer by 


1 The online project leader may or may not be responsible for the production of a hardcopy cover letter or CD 
booklet. 


* In the VMS documentation group, the online project leader sends a copy of this list to the document set 
builder and CMS librarian. 
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5.2 Scheduling the Project 


January 1.) See Section 5.4 for instructions on completing an online 
submission form. 


2 Five weeks prior to the targeted disc date, all DECW$BOOK and 
DECW$BOOKSHELF files are due to the release engineer. (For 
example, if the targeted disc date is March 6, the completed files are 
due to the release engineer no later than February 1.) 


Given these milestones, the online project leader must ensure that all files 
listed in the online submission form can be delivered for the targeted disc. 
If some problem occurring in online conversion or art conversion makes it 
obvious that a given book or bookshelf cannot be made available for the 
targeted disc, the online project leader must withdraw the book from the 
online submission form six weeks prior to the targeted disc date. 


The online project leader therefore should schedule potentially problematic 
and time-consuming work as early as possible. The following list suggests 
an optimal ordering of priorities: 


1 Art package final 


No later than eight weeks prior to targeted disc date, Graphic Services 
must have completed art conversion. The online project leader should 
meet with the art supervisor and responsible editor(s) to determine the 
time needed to convert the art. Until all art for a given book is final, 
a writer cannot insert the correct figure file names and pica sizes in a 
book. (The editor(s) actually submit the art to Graphic Services and 
deliver the final art control list to the writers.) 


2 Books ready for final production 


No later than six weeks before submittal to release engineer, the 
online documentation files (DECW$BOOK and DECW$BOOKSHELF) 
are delivered to either the editors or Graphic Services. Generally, 
all books must contain all art, must build successfully, and must be 
viewable with the DECwindows Bookreader. 


When Graphic Services is to perform the production, the online project 
leader must additionally determine whether all books in the online 
document set can be delivered at the same time or whether the set is 
submitted in installments. 


When GS does the builds, the online project leader must ensure that 
source files are delivered. 


3 Proofreading complete 


The online project leader should meet with the proofreading supervisor 
to determine the amount of time needed to proofread the online 
document set. 


1 In the VMS documentation group, the online project leader consults with the document set builder and CMS 
librarian for this date. If the work submitted to proofreading is to be batched, the document set builder 
delivers DECW$BOOK and DECW$BOOKSHELF files to proofreading. 
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These are important priorities that should be discussed at the pre- 
production meeting. The online project leader should attend this 
meeting to determine the amount time needed for the cycle. 


- Art package final—no later than eight weeks prior to submission 
- Books submitted to GS 


Depending on online or online/hardcopy process. 
See sections 1.7 and 1.8 for details on either of these 
processes. 


- Books completed by GS 


The online project leader should maintain a list of all books that must 
be proofread, indicating the type of proofreading check (complete, 
partial, spot-check) required for each book. The online project leader 
should know the approximate page count of the entire document set. 


4 Final book builds scheduled 


On these dates, final book builds for the books in the online document 
set must be performed.! 


Books undergeing online-only production are built by individual 
writers, or by Graphic Services. Books undergoing simultaneous 
online/hardcopy production are built by the Graphic Services operator. 


5 Delivery to release engineer 


On this date (no fewer than five weeks from the targeted disc date), 
the online documentation files (DECW$BOOK files) are delivered to 
the release engineer.” 


The online project leader must consider how much time will be 
required to submit the online books to the release engineer. If a 
Graphic Services operator has performed the final bookbuilds, the 
operator delivers the books to the release engineer. If the final 
bookbuilds have been performed outside of the Graphic Services 
group, the person responsible for the builds (for instance, the online 
project leader) delivers the books as agreed with the release engineer. 
If the books are produced off-site or involves a large block size or large 
doc set, they must be submitted on tape, otherwise they can negotiate 
with the release engineer about delivery. Allow an extra half-day for 
the tape backup. 


1 In the VMS documentation group, the online project leader consults with the document set builder and CMS 
librarian for this date. For online releases, the document set builder performs the final book build (that is, 
a document set build) and delivers DECW$BOOK files to the release engineer. 


* In the VMS documentation group, the online project leader consults with the document set builder and CMS 
librarian for this date. For online-only and online/hardcopy releases, the document set builder performs the 
final book builds (that is, a document set build) and delivers DECW$BOOK files to the release engineer. 
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5.3 Organizing Books and Bookshelves 


The user of the DECwindows Bookreader accesses books by scanning 
the contents of the main library and any of a series of bookshelves that 
originate from a bookshelf entry in the main library. 


Each bookshelf corresponds to a group of related books, for example, 
document set, document set kit, or document set subkit. The online project 
leader organizes the books in the online document set by performing the 
following operations: 


¢ Determining the number of bookshelves required to organize the 
document set adequately 


° Distributing the books among the defined bookshelves 
e Organizing the books within a given bookshelf 
e Organizing the bookshelves 


Once the online project leader has determined the bookshelf organization, 
he or she creates each bookshelf file in the format required by the 
DECwindows Bookreader. An example subset of bookshelf files used 

for the VMS Document Set is provided in Example 5—1 Note that the file 
names for each book contain the book’s order (2-5-2, or 2-5-2-4) number, as 
required by online submission procedures. 


It is important that the online project leader complete the organization 
of the online documentation into bookshelves prior to completing the 
online submission form (see Section 5.4). The release engineer uses this 
information to create the final bookshelf files and the preliminary product 
definition form. 


After he or she has created the necessary bookshelves, the online 

project leader examines them using the DECwindows Bookreader. If the 
bookshelves appear satisfactorily, the online project leader sends them to 
the release engineer, along with an estimate of the block size requirements 
for the complete document set.! 


5.4 Fulfilling Administrative Requirements 


To process an online document set, the online project leader is responsible 
for completing the following forms: 


1 In the VMS documentation group, the online project leader must also send the bookshelf files to the 
document set builder and CMS librarian. The document set builder can help in determining the estimated 
size of the document set. 


5-5 


Uniune rroject Leauer 
5.4 Fulfilling Administrative Requirements 


Example 5-1 VMS Document Set Bookshelf Files 


The primary bookshelf file: 


BOOK\ AA-LA95B-01_A01\Overview of VMS Documentation 
SHELF\V52VMS_RELEASE\VMS Version 5.2 Release Documents 
SHELF \V52VMS_USER\VMS and VMS DECwindows User Documents 
SHELF\V52VMs | GENERAL _USER\VMS General User Extended Set Documents 
SHELF\V52VMS | SYSTEM | MANAGEMENT \ VMS System Management Extended Set Documents 
SHELF \V52VMS_|  PROGRAMMING\ VMS Programming Extended Set Documents 

SHELF \ VMS | DECW |_PROGRAMMING\ VMS DECwindows Programming Documents 

SHELF \ V52VMs_ INSTALLATION\ VMS Installation and Operations Documents 
SHELF\V52VMS_OPTIONAL\VMS Optional Documents 


’ 


The VMS and VMS DECwindows User Documents bookshelf file: 


BOOK\ AA-MG17A-TE\Overview of VMS DECwindows 

BOOK\ AA-MG18A-TE\ VMS DECwindows User’s Guide 

BOOK\ AA-MG19A-TE\ VMS DECwindows Desktop Applications Guide 
BOOK\ AA-LA33B-01_A01\VMS License Management Utility Manual 
BOOK\ AA-LAOOB-01 | ~AO1\VMS System Manager’s Manual 

BOOK\ AA-LA98B-01 _A01\ VMS User's Manual 


The VMS General User Extended Set Documents bookshelf file: 


BOOK\ AA~LAOS5A-01 _A01\Guide to Using VMS 

BOOK\ AA-LA11A-01 ~A01\ Guide to Using VMS Command Procedures 

BOOK\ AA-LAO6A-01_A01\Guide to VMS Files and Devices 

BOOK\ AA~-LA13A-01_ AOl1\Guide to VMS Text Processing 

BOOK\ AA-LAO4A-01 AO1\Introduction to VMS 

BOOK\ AA-LA15A-01_ AO1\VAX DIGITAL Standard Runoff Reference Manual 
BOOK\ AA-LA16A-01_A01\VAX EDT Reference Manual 

BOOK\ AA-LA14B-01 AO1\VAX Text Processing Utility Manual 

BOOK\ AA~LA10A-01_A01\VMS DCL Concepts Manual 

BOOK\ AA-LA12A-01_AO1\VMS DCL Dictionary 

BOOK\ AA-NG62A-01_AO1\VMS EVE Reference Manual 

BOOK\ AA-LAO3A-01 AO1\VMS Glossary 

BOOK\ AA-LAO7A-01_AO1\VMS Mail Utility Manual 

BOOK\ AA-LAO8A-01_AO1\VMS Phone Utility Manual 

BOOK\ AA-LAOSA-01 AO1\VMS Sort/Merge Utility Manual 

BOOK\ AA-LA17A-01 AO1\VMS System Messages and Recovery Procedures Reference Volume 


Online submission form 


Eight to ten weeks prior to the targeted disc date, the online project 
leader completes the online submission form and submits it to the release 
engineer. 


To create an online submission form, the online project leader obtains the 
_ Command procedure ONLINE.COM from the release engineer. 


Execute ONLINE.COM, responding to its queries. By default, it generates 

an output file named ONLINE.LIS in your default directory. Some of the 

information it requires includes: 

¢ Contact person—the individual (for instance, online project leader) 
responsible for delivering this book or document set to the release 
engineer. 
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5.4 Fulfilling Administrative Requirements 


¢ Targeted disk shipping date—the first customer ship (FCS) date as 
listed by the online submission program. Enter the number from 1 
through 5 that corresponds to the list position of the appropriate date. 


e Special instructions—Enter licensing information in this section. 


If the document set includes multiple, books and bookshelves, perform 
the following actions: 


° Press to proceed to the next section of the command 
procedure. 


¢ Select “Edit a file.” 


¢ Begin listing each bookshelf composing the document set. List 
bookshelves you expect are most frequently used first. For each 
bookshelf: 


— Enter the bookshelf file name. 


— Supply the order number (2-5-2, or 2-5-2-4 number), exact book 
title, and block size for each book in the bookshelf. Make sure that 
you list the books in the appropriate order. 


¢ When you are finished editing, exit the file and return to 
ONLINE.COM. 


e Select “Exit this program.” 
Product Definition Form 


The release engineer uses the information supplied in the online 
submission form to create the product definition form (PDF) required 
by the SSB. The release engineer sends a copy of the PDF to the online 
project leader. 


The online project leader examines the PDF and verifies the following 
items: 


¢ Book titles 

e Order numbers and file names 

¢ Bookshelf titles and file names 

¢ Organization of bookshelves within the document set 

¢ Organization of books within bookshelves 

e Organization of books within the entire CD 
Check overall organization of disc library for potential conflicts of 
bookshelf names. 


If information is incorrect, the online project leader notifies the release 
engineer. Once all information is correct, the online project leader 

signs off on the PDF. If there are any questions relating to the names 

or organization of the bookshelves, the online project leader should consult 
with their product manager of the CD. 
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Job Requisition Forms 


If Graphic Services has agreed to perform the online proofreading or 
online builds for the document set, the online project leader ensures that 
the job requisition forms are submitted to Graphic Services requesting the 
proofreading for the entire document set. 


5.5 Coordinating the Work 


For large document sets, the online project leader works with the project 
editor to coordinate the work of Graphic Services, writers, and editors. 
This helps prevent work from being lost or forgotten. 


1 The online project leader ensures that all art work is completed in 
time for the final online build. If art needs to be converted to RAGS 
(or UTOX), the online project leader should initiate conversion as soon 
as possible. If new or revised art is required, the online project leader 
should ensure that it is submitted as soon as possible. 


2 The online project leader ensures that proofreading of documents is 
completed in time for the final online build. The online project leader 
should meet with Graphics Services to determine the amount of time 
to complete proofreading; to establish a schedule for submittal of books 
for proofreading; and to establish a date by when all proofreading 
comments must be returned to the writing group to be incorporated. 
The online project leader also works with the writers and editors to 
ensure that proofreading comments are being incorporated in time for 
the final online build. 


3 The online project leader ensures that all documents are meeting 
final production and final bookbuilding schedules. The online project 
leader also assists writers and editors to resolve any bookbuilding 
and Bookreader problems that may impact final production or final 
bookbuilding schedules. 


If a change in the status of a document (due to a bookbuilding problem, 
a Bookreader problem, or a documentation issue) will result in an 
impact to the availability of the online document, it is the online 
project leader’s responsibility to contact all concerned personnel. The 
online project leader should also work with all concerned personnel to 
resolve the problem. 


The online project leader may wish to set up regular status meetings or 
other update mechanisms to ensure that work is proceeding according to 
schedule. The regular status meetings would likely include the project 
editor and representatives from Graphic Services and SSB. 


5.6 Providing Books to Release Engineer 


Once all books in the document set are built for the final time, the project 
leader is responsible for the following tasks:! 


1 In the VMS documentation group, the online project leader notifies the document set builder when all work 
on all books has been completed. The document set builder then builds the final document set, renames the 
files appropriately, stages the bookshelves and books, and delivers the files to the release engineer. 
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Ensure that the final DECW$BOOK files are renamed from 
the IlpnPRO.DECW$BOOK filename form to the order number 
form (for example, from 1245PRO.DECW$BOOK to AA-JT84A- 
TE.DECW$BOOK). The renaming needs only to be done on the 
REDINK system. 


Define the DECW$BOOK logical to point to the directory in which 
the online books and bookshelves reside, and run the DECwindows 
Bookreader. Using the DECwindows Bookreader, perform the following 
procedures: 


— Verify that the bookshelf files include each book in the document 
set. 


— Verify that each bookshelf entry calls up the correct book. 
— Verify that each book can be opened. 


Ensure that all DECW$BOOK files have been transfered to the release 
directory. The process by which the files are transferred depends upon 
an arrangement between Graphic Services and the release engineer. 


Generally, within Cost Center 32V, the online project leader simply 
copies final online books and the bookshelf files referencing them to: 


REDINK: :REDINKS$DUA2: [OLPROD .mmmCD } 
Certain large document sets, however, may require a backup tape. 


Outside of Cost Center 32V, a backup tape is mandatory. Use the 
following procedure to create and submit the backup tape: 


1 Obtain two new 2400-foot magtapes. 
2 On the label, include the following information: 
°¢ Creation date 
e Saveset name 
¢ Product name 
¢ Contact person (person who created tape) 
3 Mount tape on tape drive. 
Log into a privileged account (if necessary) 
§ Enter the following commands: 


$ INIT/DENSITY=1600 device-name tape-label 

$ MOUNT/FOR device-name 

$ BACKUP/VERIFY/LIST=sitegroup.LIS disk: [directory] *.*;* - 
_§ device-name: sitegroup.SAV/SAVE_SET 


6 When the backup operation has completed, dismount the tape, 
using the following command:. 


§ DISMOUNT device-name 
7 Remove tape from tape drive and remove the write ring. 
8 Print the LIS file. 
9 Logout. 
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5.6 Providing Books to Release Engineer 


10 Ship both tapes and a copy of the .LIS file in bubble wrap 
envelopes to: 


Susan Prochaska (or current release engineer) 
ZK01-2/F02 

Digital Equipment Corporation 

110 Spit Brook Road 

Nashua, NH 03062-2642 


Note: Tapes should be mailed in enough time to arrive at Spit 
Brook three days prior to the SQM submission date. 


e Notify the release engineer that books are available in the release 
directory, or that a tape is available for restoring. 
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converting hardcopy to online 3-4 to 3-6 
creating for final draft> 2-5 
creating for online manuals + 2-3 
creating for review drafts > 2-3 
output formats > 2-5 
proofreading: 3-0 


given to writers 3-6, 3-8 
requesting: 3-5 
requesting for initial book conversion > 3-7 
reviewing > 3-5, 3-7 
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D 


DECWSBOOKFIG file> 2-20, 2-28 
DECWS$BOOK file 

renaming to include order number > 5-0 
DECWS$BOOKSHELF file 

creating for online document set> 5-5 

missing > 2-17 


Docplans (cont’d.) 

writing for online manuals * 2-2 
DOCUMENT command line 

for hardcopy books * 2-29 

for online books - 2-29 
DVC-E-BOOKABOPT error * 2-17 
DVC-E-OUTPUTFAIL + 2-18 
DVC-W-SPECIALERROR + 2-28, 2-29, 2-32 
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Online productions 2-40 
Online submission form > 5-2 
completing > 5-6 
ONLINE_BOOKBUILDING notes conference > 2-2 
ONLINE_CLEANUP.COM > 2-26 to 2-27 


index—4 


p 


PAGE COORDINATION LOST error * 2-17, 2-33 
<PAGE> tage 2-23 
Part ' 
online coding requirements > 2-19 to 2-24 
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